Prérequis et rôles requis Autorisations nécessaires Spécification de la version du pipeline Spécification du chemin d'ingestion Création de pipelines Suivi de l'état de la création du pipeline Utiliser des plans pour créer un pipeline

Création de pipelines OpenSearch Amazon Ingestion

Un pipeline est le mécanisme utilisé OpenSearch par Amazon Ingestion pour déplacer les données de leur source (d'où proviennent les données) vers leur récepteur (où les données sont acheminées). Dans OpenSearch Ingestion, le récepteur sera toujours un domaine Amazon OpenSearch Service unique, tandis que la source de vos données peut être des clients tels qu'Amazon S3, Fluent Bit ou le OpenTelemetry Collector.

Pour plus d'informations, consultez la section Pipelines dans la OpenSearch documentation.

Rubriques

Prérequis et rôles requis
Autorisations nécessaires
Spécification de la version du pipeline
Spécification du chemin d'ingestion
Création de pipelines
Suivi de l'état de la création du pipeline
Utiliser des plans pour créer un pipeline

Prérequis et rôles requis

Pour créer un pipeline d' OpenSearch ingestion, vous devez disposer des ressources suivantes :

Rôle IAM qu' OpenSearch Ingestion assumera pour écrire dans le récepteur. Vous allez inclure cet ARN de rôle dans la configuration de votre pipeline.
Un domaine de OpenSearch service ou une collection OpenSearch sans serveur servant de récepteur. Si vous écrivez sur un domaine, celui-ci doit exécuter la OpenSearch version 1.0 ou une version ultérieure, ou Elasticsearch 7.4 ou une version ultérieure. Le récepteur doit disposer d'une politique d'accès qui accorde les autorisations appropriées à votre rôle de pipeline IAM.

Pour obtenir des instructions sur la création de ces ressources, consultez les rubriques suivantes :

Note

Si vous écrivez dans un domaine qui utilise un contrôle d'accès précis, vous devez effectuer des étapes supplémentaires. veuillez consulter Étape 3 : Cartographier le rôle du pipeline (uniquement pour les domaines qui utilisent un contrôle d'accès précis).

Autorisations nécessaires

OpenSearch L'ingestion utilise les autorisations IAM suivantes pour créer des pipelines :

osis:CreatePipeline— Créez un pipeline.
osis:ValidatePipeline— Vérifiez si une configuration de pipeline est valide.
iam:PassRole— Transmettez le rôle de pipeline à OpenSearch Ingestion afin qu'elle puisse écrire des données dans le domaine. Cette autorisation doit porter sur la ressource du rôle du pipeline (l'ARN que vous spécifiez pour l'sts_role_arnoption dans la configuration du pipeline), ou simplement * si vous prévoyez d'utiliser des rôles différents dans chaque pipeline.

Par exemple, la politique suivante autorise la création d'un pipeline :


{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Resource":"*",
         "Action":[
            "osis:CreatePipeline",
            "osis:ListPipelineBlueprints",
            "osis:ValidatePipeline"
         ]
      },
      {
         "Resource":[
            "arn:aws:iam::{your-account-id}:role/{pipeline-role}"
         ],
         "Effect":"Allow",
         "Action":[
            "iam:PassRole"
         ]
      }
   ]
}

OpenSearch L'ingestion inclut également une autorisation appeléeosis:Ingest, qui est requise pour envoyer des demandes signées au pipeline à l'aide de Signature Version 4. Pour plus d’informations, consultez Création d'un rôle d'ingestion.

Note

En outre, le premier utilisateur à créer un pipeline dans un compte doit disposer des autorisations nécessaires pour effectuer cette iam:CreateServiceLinkedRole action. Pour plus d'informations, consultez la section ressource du rôle du pipeline.

Pour plus d'informations sur chaque autorisation, consultez la section Actions, ressources et clés de condition pour OpenSearch l'ingestion dans la référence d'autorisation de service.

Spécification de la version du pipeline

Lorsque vous configurez un pipeline, vous devez spécifier la version principale de Data Prepper que le pipeline exécutera. Pour spécifier la version, incluez l'versionoption dans la configuration de votre pipeline :


version: "2"
log-pipeline:
  source:
    ...

Lorsque vous choisissez Create, OpenSearch Ingestion détermine la dernière version mineure disponible de la version principale que vous spécifiez et approvisionne le pipeline avec cette version. Par exemple, si vous spécifiez version: "2" que la dernière version prise en charge de Data Prepper est 2.1.1, OpenSearch Ingestion approvisionne votre pipeline avec la version 2.1.1. Nous n'affichons pas publiquement la version mineure que votre pipeline exécute.

Afin de mettre à niveau votre pipeline lorsqu'une nouvelle version majeure de Data Prepper est disponible, modifiez la configuration du pipeline et spécifiez la nouvelle version. Vous ne pouvez pas rétrograder un pipeline vers une version antérieure.

Note

OpenSearch Ingestion ne prend pas immédiatement en charge les nouvelles versions de Data Prepper dès leur sortie. Il y aura un certain décalage entre le moment où une nouvelle version sera accessible au public et le moment où elle sera prise en charge dans OpenSearch Ingestion. En outre, OpenSearch Ingestion peut explicitement ne pas prendre en charge complètement certaines versions majeures ou mineures. Pour obtenir la liste complète, consultez Versions de Data Prepper prises en charge.

Chaque fois que vous apportez une modification à votre pipeline qui lance un déploiement bleu/vert, OpenSearch Ingestion peut le mettre à niveau vers la dernière version mineure de la version majeure actuellement configurée dans le fichier YAML du pipeline. Pour plus d'informations, consultezDéploiements bleu/vert pour les mises à jour du pipeline. OpenSearch L'ingestion ne peut pas modifier la version principale de votre pipeline à moins que vous ne mettiez explicitement à jour l'versionoption dans la configuration du pipeline.

Spécification du chemin d'ingestion

Pour les sources basées sur le pull telles que les métriques OTel trace et OTel, OpenSearch l'ingestion nécessite l'pathoption supplémentaire dans votre configuration source. Le chemin est une chaîne telle que/log/ingest, qui représente le chemin de l'URI pour l'ingestion. Ce chemin définit l'URI que vous utilisez pour envoyer des données au pipeline.

Supposons, par exemple, que vous spécifiez le sous-pipeline d'entrée suivant pour un pipeline d'ingestion nommé logs :


entry-pipeline:
  source:
    http:
      path: "/my/test_path"

Lorsque vous ingérez des données dans le pipeline, vous devez spécifier le point de terminaison suivant dans la configuration de votre client :https://logs-abcdefgh.us-west-2.osis.amazonaws.com/my/test_path.

Le chemin doit commencer par une barre oblique (/) et peut contenir les caractères spéciaux « - », « _ », « . ', et'/', ainsi que l'${pipelineName}espace réservé. Si vous utilisez ${pipelineName} (tel quepath: "/${pipelineName}/test_path"), la variable est remplacée par le nom du sous-pipeline associé. Dans cet exemple, ce serait le cashttps://logs.us-west-2.osis.amazonaws.com/entry-pipeline/test_path.

Création de pipelines

Cette section décrit comment créer des pipelines d' OpenSearch ingestion à l'aide de la console de OpenSearch service et du AWS CLI.

Pour créer un pipeline

Connectez-vous à la console Amazon OpenSearch Service à l'adresse https://console.aws.amazon.com/aos/home.
Choisissez Pipelines dans le volet de navigation de gauche, puis choisissez Créer un pipeline.
Entrez un nom pour le pipeline.
(Facultatif) Choisissez Activer la mémoire tampon persistante. Une mémoire tampon persistante stocke vos données dans une mémoire tampon sur disque sur plusieurs zones de disponibilité. Pour plus d'informations, consultez la section Mise en mémoire tampon persistante. Si vous activez la mémoire tampon persistante, sélectionnez la AWS Key Management Service clé pour chiffrer les données de la mémoire tampon.
Configurez la capacité minimale et maximale du pipeline en unités de OpenSearch calcul d'ingestion (OCU). Pour plus d’informations, consultez Dimensionnement des pipelines.
Sous Configuration du pipeline, indiquez la configuration de votre pipeline au format YAML. Un seul fichier de configuration de pipeline peut contenir de 1 à 10 sous-pipelines. Chaque sous-pipeline est une combinaison d'une source unique, de zéro ou plusieurs processeurs et d'un seul récepteur. Pour OpenSearch l'ingestion, le récepteur doit toujours être un domaine OpenSearch de service. Pour obtenir la liste des options prises en charge, consultezPlug-ins et options pris en charge pour les pipelines OpenSearch Amazon Ingestion.

Note
Vous devez inclure les sigv4 options sts_role_arn et dans chaque sous-pipeline. Le pipeline assume le rôle défini dans sts_role_arn pour signer les demandes adressées au domaine. Pour plus d’informations, consultez Accorder aux OpenSearch pipelines Amazon Ingestion l'accès aux domaines.

L'exemple de fichier de configuration suivant utilise la source HTTP et les plug-ins Grok pour traiter les données de journal non structurées et les envoyer à un domaine de OpenSearch service. Le sous-pipeline est nommélog-pipeline.
```
version: "2"
log-pipeline:
  source:
    http:
      path: "/log/ingest"
  processor:
    - grok:
        match:
          log: [ '%{COMMONAPACHELOG}' ]
    - date:
        from_time_received: true
        destination: "@timestamp"
  sink:
    - opensearch:
        hosts: [ "https://search-my-domain.us-east-1.es.amazonaws.com" ]
        index: "apache_logs"
        aws:
          sts_role_arn: "arn:aws:iam::123456789012:role/{pipeline-role}"
          region: "us-east-1"
```
Note
Si vous spécifiez plusieurs récepteurs dans une définition de pipeline YAML, ils doivent tous appartenir au même domaine OpenSearch de service. Un pipeline d' OpenSearch ingestion ne peut pas écrire dans plusieurs domaines différents.

Vous pouvez créer votre propre configuration de pipeline ou choisir Charger un fichier et importer une configuration existante pour un pipeline Data Prepper autogéré. Vous pouvez également utiliser un plan de configuration.
Après avoir configuré votre pipeline, choisissez Valider le pipeline pour confirmer que votre configuration est correcte. Si la validation échoue, corrigez les erreurs et relancez la validation.

Sous Configuration réseau, choisissez Accès VPC ou Accès public. Si vous choisissez Public access (Accès public), passez à l'étape suivante. Si vous choisissez l'accès VPC, configurez les paramètres suivants :

Paramètre	Description
Gestion des terminaux	Choisissez si vous souhaitez créer vous-même vos points de terminaison VPC ou laisser Ingestion les créer OpenSearch pour vous. La gestion des points de terminaison est par défaut celle des points de terminaison gérés par OpenSearch Ingestion.
VPC	Choisissez le cloud privé virtuel (VPC) que vous souhaitez utiliser. Le VPC et le pipeline doivent être identiques. Région AWS
Sous-réseaux	Choisissez un ou plusieurs sous-réseaux. OpenSearch Le service placera un point de terminaison VPC et des interfaces réseau élastiques dans les sous-réseaux.
Groupes de sécurité	Choisissez un ou plusieurs groupes de sécurité VPC qui permettent à l'application requise d'atteindre le pipeline d' OpenSearch ingestion sur les ports (80 ou 443) et les protocoles (HTTP ou HTTPS) exposés par le pipeline.
Options de fixation en VPC	Si votre source est un point de terminaison autogéré, attachez votre pipeline à un VPC. Choisissez l'une des options CIDR par défaut fournies ou utilisez un CIDR personnalisé.

Pour plus d’informations, consultez Configuration de l'accès VPC pour les pipelines Amazon Ingestion OpenSearch .

(Facultatif) Sous Tags, ajoutez une ou plusieurs balises (paires clé-valeur) à votre pipeline. Pour plus d’informations, consultez Balisage des pipelines d'OpenSearchingestion Amazon.
(Facultatif) Sous Options de publication des journaux, activez la publication des journaux du pipeline sur Amazon CloudWatch Logs. Nous vous recommandons d'activer la publication des journaux afin de pouvoir résoudre plus facilement les problèmes liés au pipeline. Pour plus d’informations, consultez Surveillance des journaux du pipeline.
Choisissez Suivant.
Passez en revue la configuration de votre pipeline et choisissez Create.

OpenSearch Ingestion exécute un processus asynchrone pour créer le pipeline. Une fois que l'état du pipeline est Active atteint, vous pouvez commencer à ingérer des données.

La commande create-pipeline accepte la configuration du pipeline sous forme de chaîne ou dans un fichier .yaml. Si vous fournissez la configuration sous forme de chaîne, chaque nouvelle ligne doit être supprimée avec\n. Par exemple, "log-pipeline:\n source:\n http:\n processor:\n - grok:\n ...

L'exemple de commande suivant crée un pipeline avec la configuration suivante :

Minimum de 4 OCU par ingestion, maximum de 10 OCU par ingestion
Provisionné dans un cloud privé virtuel (VPC)
Publication de journaux activée


aws osis create-pipeline \
  --pipeline-name my-pipeline \
  --min-units 4 \
  --max-units 10 \
  --log-publishing-options  IsLoggingEnabled=true,CloudWatchLogDestination={LogGroup="MyLogGroup"} \
  --vpc-options SecurityGroupIds={sg-12345678,sg-9012345},SubnetIds=subnet-1212234567834asdf \
  --pipeline-configuration-body "file://pipeline-config.yaml"

OpenSearch Ingestion exécute un processus asynchrone pour créer le pipeline. Une fois que l'état du pipeline est Active atteint, vous pouvez commencer à ingérer des données. Pour vérifier l'état du pipeline, utilisez la GetPipelinecommande.

Pour créer un pipeline d' OpenSearch ingestion à l'aide de OpenSearch l'API d'ingestion, appelez l'CreatePipelineopération.

Une fois votre pipeline créé avec succès, vous pouvez configurer votre client et commencer à ingérer des données dans votre domaine OpenSearch de service. Pour plus d’informations, consultez Utilisation des intégrations du OpenSearch pipeline Amazon Ingestion.

Suivi de l'état de la création du pipeline

Vous pouvez suivre l'état d'un pipeline au fur et à mesure qu' OpenSearch Ingestion le provisionne et le prépare à ingérer des données.

Une fois que vous avez initialement créé un pipeline, celui-ci passe par plusieurs étapes car OpenSearch Ingestion le prépare à ingérer des données. Pour visualiser les différentes étapes de création du pipeline, choisissez le nom du pipeline pour voir sa page de paramètres du pipeline. Sous État, choisissez Afficher les détails.

Un pipeline passe par les étapes suivantes avant d'être disponible pour l'ingestion de données :

Validation — Validation de la configuration du pipeline. Lorsque cette étape est terminée, toutes les validations sont réussies.
Création d'un environnement : préparation et approvisionnement des ressources. Lorsque cette étape est terminée, le nouvel environnement de pipeline a été créé.
Déployer le pipeline : déploiement du pipeline. Lorsque cette étape est terminée, le pipeline a été déployé avec succès.
Vérifier l'état du pipeline : vérification de l'état du pipeline. Lorsque cette étape est terminée, tous les bilans de santé sont passés avec succès.
Activer le trafic — Permettre au pipeline d'ingérer des données. Lorsque cette étape est terminée, vous pouvez commencer à ingérer des données dans le pipeline.

Utilisez la get-pipeline-change-progresscommande pour vérifier l'état d'un pipeline. La AWS CLI demande suivante vérifie l'état d'un pipeline nommé my-pipeline :


aws osis get-pipeline-change-progress \
    --pipeline-name my-pipeline

Réponse :


{
   "ChangeProgressStatuses": {
      "ChangeProgressStages": [ 
         { 
            "Description": "Validating pipeline configuration",
            "LastUpdated": 1.671055851E9,
            "Name": "VALIDATION",
            "Status": "PENDING"
         }
      ],
      "StartTime": 1.671055851E9,
      "Status": "PROCESSING",
      "TotalNumberOfStages": 5
   }
}

Pour suivre l'état de la création du pipeline à l'aide de OpenSearch l'API Ingestion, appelez l'GetPipelineChangeProgressopération.

Utiliser des plans pour créer un pipeline

Plutôt que de créer une définition de pipeline à partir de zéro, vous pouvez utiliser des plans de configuration, qui sont des modèles YAML préconfigurés pour les scénarios d'ingestion courants tels que Trace Analytics ou les journaux Apache. Les plans de configuration vous aident à approvisionner facilement des pipelines sans avoir à créer une configuration à partir de zéro.

Pour utiliser un plan de pipeline

Connectez-vous à la console Amazon OpenSearch Service à l'adresse https://console.aws.amazon.com/aos/home.
Choisissez Pipelines dans le volet de navigation de gauche, puis choisissez Créer un pipeline.
Sélectionnez un plan. La configuration du pipeline est renseignée avec un sous-pipeline correspondant au cas d'utilisation que vous avez sélectionné.
Passez en revue le texte commenté qui vous guide tout au long de la configuration du plan.

Important
Le plan du pipeline n'est pas valide tel quel. Vous devez apporter quelques modifications, telles que la fourniture de l'ARN Région AWS et du rôle à utiliser pour l'authentification, sinon la validation du pipeline échouera.

Pour obtenir une liste de tous les plans disponibles à l'aide du AWS CLI, envoyez une list-pipeline-blueprintsdemande.


aws osis list-pipeline-blueprints

La demande renvoie une liste de tous les plans disponibles.

Pour obtenir des informations plus détaillées sur un plan spécifique, utilisez la get-pipeline-blueprintcommande :


aws osis get-pipeline-blueprint --blueprint-name AWS-ApacheLogPipeline

Cette requête renvoie le contenu du plan du pipeline de logs Apache :


{
   "Blueprint":{
      "PipelineConfigurationBody":"###\n  # Limitations: https://docs.aws.amazon.com/opensearch-service/latest/ingestion/ingestion.html#ingestion-limitations\n###\n###\n  # apache-log-pipeline:\n    # This pipeline receives logs via http (e.g. FluentBit), extracts important values from the logs by matching\n    # the value in the 'log' key against the grok common Apache log pattern. The grokked logs are then sent\n    # to OpenSearch to an index named 'logs'\n###\n\nversion: \"2\"\napache-log-pipeline:\n  source:\n    http:\n      # Provide the path for ingestion. ${pipelineName} will be replaced with pipeline name configured for this pipeline.\n      # In this case it would be \"/apache-log-pipeline/logs\". This will be the FluentBit output URI value.\n      path: \"/${pipelineName}/logs\"\n  processor:\n    - grok:\n        match:\n          log: [ \"%{COMMONAPACHELOG_DATATYPED}\" ]\n  sink:\n    - opensearch:\n        # Provide an AWS OpenSearch Service domain endpoint\n        # hosts: [ \"https://search-mydomain-1a2a3a4a5a6a7a8a9a0a9a8a7a.us-east-1.es.amazonaws.com\" ]\n        aws:\n          # Provide a Role ARN with access to the domain. This role should have a trust relationship with osis-pipelines.amazonaws.com\n          # sts_role_arn: \"arn:aws:iam::123456789012:role/Example-Role\"\n          # Provide the region of the domain.\n          # region: \"us-east-1\"\n          # Enable the 'serverless' flag if the sink is an Amazon OpenSearch Serverless collection\n          # serverless: true\n        index: \"logs\"\n        # Enable the S3 DLQ to capture any failed requests in an S3 bucket\n        # dlq:\n          # s3:\n            # Provide an S3 bucket\n            # bucket: \"your-dlq-bucket-name\"\n            # Provide a key path prefix for the failed requests\n            # key_path_prefix: \"${pipelineName}/logs/dlq\"\n            # Provide the region of the bucket.\n            # region: \"us-east-1\"\n            # Provide a Role ARN with access to the bucket. This role should have a trust relationship with osis-pipelines.amazonaws.com\n            # sts_role_arn: \"arn:aws:iam::123456789012:role/Example-Role\"\n",
      "BlueprintName":"AWS-ApacheLogPipeline"
   }
}

Pour obtenir des informations sur les plans de pipeline à l'aide de OpenSearch l'API d'ingestion, utilisez les GetPipelineBlueprintopérations ListPipelineBlueprintset.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Vue d'ensemble des fonctionnalités du pipeline

Affichage des pipelines

Création de pipelines OpenSearch Amazon Ingestion

Rubriques

Prérequis et rôles requis

Note

Autorisations nécessaires

Note

Spécification de la version du pipeline

Note

Spécification du chemin d'ingestion

Création de pipelines

Pour créer un pipeline

Note

Note

Suivi de l'état de la création du pipeline

Utiliser des plans pour créer un pipeline

Pour utiliser un plan de pipeline

Important