View a markdown version of this page

Crea un componente personalizzato con Image Builder - EC2 Image Builder

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Crea un componente personalizzato con Image Builder

Dopo aver completato il documento del componente, puoi utilizzarlo per creare un componente personalizzato utilizzabile dalle tue ricette di Image Builder. Puoi creare un componente personalizzato dalla console di Image Builder, dall'API o dagli SDK o dalla riga di comando. Per ulteriori informazioni su come creare un componente personalizzato con parametri di input e utilizzarlo nelle ricette, consulta Tutorial: creare un componente personalizzato con parametri di input.

Le sezioni seguenti mostrano come creare componenti dalla console, AWS CLI, o AWS Strumenti per PowerShell.

Crea un componente personalizzato nella console

Suggerimento

Ora puoi creare con l'IA. Per ulteriori informazioni, consulta Crea e aggiorna risorse con l'IA - Anteprima.

Per creare un AWSTOE componente dell'applicazione dalla console Image Builder, segui questi passaggi:

  1. Apri la console EC2 Image Builder all'indirizzo https://console.aws.amazon.com/imagebuilder/.

  2. Seleziona Componenti dal pannello di navigazione. Quindi seleziona Crea componente.

  3. Sul Crea componente pagina, sotto Dettagli dei componenti, inserisci quanto segue:

    1. Image Operating System (OS). Specifica il sistema operativo con cui il componente è compatibile.

    2. Categoria di componente. Dal menu a discesa, seleziona il tipo di componente di build o test che stai creando.

    3. Nome del componente. Inserite un nome per il componente.

    4. Versione del componente. Inserite il numero di versione del componente.

    5. Descrizione. Fornisci una descrizione opzionale per aiutarti a identificare il componente.

    6. Modifica la descrizione. Fornisci una descrizione opzionale per aiutarti a comprendere le modifiche apportate a questa versione del componente.

  4. Nel Documento di definizione sezione, l'opzione predefinita è Definire il contenuto del documento. Il documento del componente definisce le azioni che Image Builder esegue sulle istanze di build e test per creare l'immagine.

    Nel Contenuto casella, inserisci il contenuto del documento del componente YAML. Per iniziare con un Ciao mondo esempio per Linux, scegli Usa un esempio opzione. Per saperne di più su come creare un documento componente YAML o copiare e incollare Aggiorna il sistema operativo esempio tratto da quella pagina, vedi Creare un documento componente YAML per componenti personalizzati in Image Builder.

  5. Dopo aver inserito i dettagli del componente, seleziona Crea componente.

    Nota

    Per vedere il tuo nuovo componente quando crei o aggiorni una ricetta, applica il Di mia proprietà filtrare fino all'elenco dei componenti di build o test. Il filtro si trova nella parte superiore dell'elenco dei componenti, accanto alla casella di ricerca.

  6. Per eliminare un componente, dal Componenti pagina, seleziona la casella di controllo accanto al componente che desideri eliminare. Dal Azioni menu a discesa, seleziona Elimina componente.

Aggiornare un componente

Per creare una nuova versione del componente, segui questi passaggi:

  1. A seconda di dove inizi:

    • Dal Componenti pagina di elenco: seleziona la casella di controllo accanto al nome del componente, quindi seleziona Crea una nuova versione dal Azioni menu.

    • Dalla pagina dei dettagli del componente, scegli Crea una nuova versione pulsante nell'angolo in alto a destra dell'intestazione.

  2. Le informazioni sul componente sono già compilate con i valori correnti quando Crea componente visualizzazioni di pagina. Segui i passaggi per creare un componente per aggiornare il componente. Assicurati di inserire una versione semantica univoca nel Versione del componente. Per saperne di più sul controllo delle versioni semantiche per le risorse di Image Builder, vedi Versionamento semantico in Image Builder.

Crea un componente personalizzato da AWS CLI

In questa sezione, imparerai come configurare e utilizzare i comandi di Image Builder nel AWS CLI per creare un AWSTOE componente dell'applicazione, come segue:

  • Carica il documento del componente YAML in un bucket S3 a cui puoi fare riferimento dalla riga di comando.

  • Crea il AWSTOE componente dell'applicazione con create-component comando.

  • Elenca le versioni dei componenti con list-components comando e un filtro dei nomi per vedere quali versioni esistono già. È possibile utilizzare l'output per determinare quale dovrebbe essere la prossima versione per gli aggiornamenti.

Per creare un AWSTOE componente applicativo da un documento YAML di input, seguite i passaggi corrispondenti alla piattaforma del sistema operativo dell'immagine.

Linux
Archivia il documento relativo al componente dell'applicazione in Amazon S3

Puoi usare un bucket S3 come repository per i tuoi AWSTOE documento sorgente del componente dell'applicazione. Per archiviare il documento del componente, segui questi passaggi:

  • Carica il documento su Amazon S3

    Se il documento è inferiore a 64 KB, puoi saltare questo passaggio. I documenti di dimensioni pari o superiori a 64 KB devono essere archiviati in Amazon S3.

    aws s3 cp update-linux-os.yaml s3://amzn-s3-demo-destination-bucket/my-path/update-linux-os.yaml
Crea un componente dal documento YAML

Per semplificare il create-component comando che usi in AWS CLI, crea un file JSON che contenga tutti i parametri del componente che desideri passare al comando. Includi la posizione del update-linux-os.yaml documento che hai creato in precedenza. Il uri la coppia chiave-valore contiene il riferimento al file.

Nota

La convenzione di denominazione per i valori dei dati nel file JSON segue lo schema specificato per i parametri di richiesta di operazione dell'API Image Builder. Per esaminare i parametri di richiesta dei comandi API, consulta CreateComponent comando nel Riferimento all'API EC2 Image Builder.

Per fornire i valori dei dati come parametri della riga di comando, fate riferimento ai nomi dei parametri specificati nella AWS CLI Riferimento al comando.

  1. Creazione di un file JSON di input nella CLI

    Usa uno strumento di modifica dei file per creare un file denominato create-update-linux-os-component.json. Includi i seguenti contenuti:

    { "name": "update-linux-os", "semanticVersion": "1.1.2", "description": "An example component that updates the Linux operating system", "changeDescription": "Initial version.", "platform": "Linux", "uri": "s3://amzn-s3-demo-destination-bucket/my-path/update-linux-os.yaml", "kmsKeyId": "arn:aws:kms:us-west-2:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "tags": { "my-tag-key-purpose": "security-updates" } }
  2. Crea il componente

    Utilizzate il comando seguente per creare il componente, facendo riferimento al nome del file JSON creato nel passaggio precedente:

    aws imagebuilder create-component --cli-input-json file://create-update-linux-os-component.json
    Nota
    • È necessario includere l'annotazione file:// all'inizio del percorso del file JSON.

    • Il percorso del file JSON deve seguire la convenzione appropriata per il sistema operativo di base in cui si esegue il comando. Ad esempio, Windows utilizza la barra rovesciata (\) per fare riferimento al percorso della directory, mentre Linux e macOS utilizzano la barra rovesciata (/).

Windows
Archivia il documento relativo ai componenti dell'applicazione in Amazon S3

Puoi usare un bucket S3 come repository per i tuoi AWSTOE documento sorgente del componente dell'applicazione. Per archiviare il documento del componente, segui questi passaggi:

  • Carica il documento su Amazon S3

    Se il documento è inferiore a 64 KB, puoi saltare questo passaggio. I documenti di dimensioni pari o superiori a 64 KB devono essere archiviati in Amazon S3.

    aws s3 cp update-windows-os.yaml s3://amzn-s3-demo-destination-bucket/my-path/update-windows-os.yaml
Crea un componente dal documento YAML

Per semplificare il create-component comando che usi in AWS CLI, crea un file JSON che contenga tutti i parametri del componente che desideri passare al comando. Includi la posizione del update-windows-os.yaml documento che hai creato in precedenza. Il uri la coppia chiave-valore contiene il riferimento al file.

Nota

La convenzione di denominazione per i valori dei dati nel file JSON segue lo schema specificato per i parametri di richiesta di operazione dell'API Image Builder. Per esaminare i parametri di richiesta dei comandi API, consulta CreateComponent comando nel Riferimento all'API EC2 Image Builder.

Per fornire i valori dei dati come parametri della riga di comando, fate riferimento ai nomi dei parametri specificati nella AWS CLI Riferimento al comando..

  1. Creazione di un file JSON di input nella CLI

    Usa uno strumento di modifica dei file per creare un file denominato create-update-windows-os-component.json. Includi i seguenti contenuti:

    { "name": "update-windows-os", "semanticVersion": "1.1.2", "description": "An example component that updates the Windows operating system.", "changeDescription": "Initial version.", "platform": "Windows", "uri": "s3://amzn-s3-demo-destination-bucket/my-path/update-windows-os.yaml", "kmsKeyId": "arn:aws:kms:us-west-2:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "tags": { "my-tag-key-purpose": "security-updates" } }
    Nota
    • È necessario includere l'annotazione file:// all'inizio del percorso del file JSON.

    • Il percorso del file JSON deve seguire la convenzione appropriata per il sistema operativo di base in cui si esegue il comando. Ad esempio, Windows utilizza la barra rovesciata (\) per fare riferimento al percorso della directory, mentre Linux e macOS utilizzano la barra rovesciata (/).

  2. Crea il componente

    Utilizzate il comando seguente per creare il componente, facendo riferimento al nome del file JSON creato nel passaggio precedente:

    aws imagebuilder create-component --cli-input-json file://create-update-windows-os-component.json
    Nota
    • È necessario includere l'annotazione file:// all'inizio del percorso del file JSON.

    • Il percorso del file JSON deve seguire la convenzione appropriata per il sistema operativo di base in cui si esegue il comando. Ad esempio, Windows utilizza la barra rovesciata (\) per fare riferimento al percorso della directory, mentre Linux e macOS utilizzano la barra rovesciata (/).

macOS
Archivia il documento relativo ai componenti dell'applicazione in Amazon S3

Puoi usare un bucket S3 come repository per i tuoi AWSTOE documento sorgente del componente dell'applicazione. Per archiviare il documento del componente, segui questi passaggi:

  • Carica il documento su Amazon S3

    Se il documento è inferiore a 64 KB, puoi saltare questo passaggio. I documenti di dimensioni pari o superiori a 64 KB devono essere archiviati in Amazon S3.

    aws s3 cp wget-macos.yaml s3://amzn-s3-demo-destination-bucket/my-path/wget-macos.yaml
Crea un componente dal documento YAML

Per semplificare il create-component comando che usi in AWS CLI, crea un file JSON che contenga tutti i parametri del componente che desideri passare al comando. Includi la posizione del wget-macos.yaml documento che hai creato in precedenza. Il uri la coppia chiave-valore contiene il riferimento al file.

Nota

La convenzione di denominazione per i valori dei dati nel file JSON segue lo schema specificato per i parametri di richiesta di operazione dell'API Image Builder. Per esaminare i parametri della richiesta dei comandi API, consulta la CreateComponent comando nel Riferimento all'API EC2 Image Builder.

Per fornire i valori dei dati come parametri della riga di comando, fate riferimento ai nomi dei parametri specificati nella AWS CLI Riferimento al comando.

  1. Creazione di un file JSON di input nella CLI

    Usa uno strumento di modifica dei file per creare un file denominato install-wget-macos-component.json. Includi i seguenti contenuti:

    { "name": "install-wget-macos-component", "semanticVersion": "1.1.2", "description": "An example component that installs and verifies the wget utility on macOS.", "changeDescription": "Initial version.", "platform": "macOS", "uri": "s3://amzn-s3-demo-destination-bucket/my-path/wget-macos.yaml", "kmsKeyId": "arn:aws:kms:us-west-2:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "tags": { "my-tag-key-purpose": "install-software" } }
  2. Crea il componente

    Utilizzate il comando seguente per creare il componente, facendo riferimento al nome del file JSON creato nel passaggio precedente:

    aws imagebuilder create-component --cli-input-json file://install-wget-macos-component.json
    Nota
    • È necessario includere l'annotazione file:// all'inizio del percorso del file JSON.

    • Il percorso del file JSON deve seguire la convenzione appropriata per il sistema operativo di base in cui si esegue il comando. Ad esempio, Windows utilizza la barra rovesciata (\) per fare riferimento al percorso della directory, mentre Linux e macOS utilizzano la barra rovesciata (/).

AWSTOE controllo delle versioni dei componenti per gli aggiornamenti

AWSTOE i nomi e le versioni dei componenti sono incorporati nell'Amazon Resource Name (ARN) del componente, dopo il prefisso del componente. Ogni nuova versione di un componente ha il suo ARN univoco. I passaggi per creare una nuova versione sono esattamente gli stessi per creare un nuovo componente, purché la versione semantica sia univoca per il nome del componente. Per saperne di più sul controllo delle versioni semantiche per le risorse di Image Builder, vedi Versionamento semantico in Image Builder.

Per assicurarti di assegnare la versione logica successiva, ottieni prima un elenco delle versioni esistenti per il componente che desideri modificare.

AWS CLI

Usate il list-components comando con AWS CLI e filtra in base al nome.

In questo esempio, filtrate in base al nome del componente creato negli esempi precedenti di Linux. Per elencare il componente che hai creato, usa il valore di name parametro dal file JSON che hai usato in create-component comando:

aws imagebuilder list-components --filters name="name",values="update-linux-os" { "requestId": "123a4567-b890-123c-45d6-ef789ab0cd1e", "componentVersionList": [ { "arn": "arn:aws:imagebuilder:us-west-2:111122223333:component/update-linux-os/1.0.0", "name": "update-linux-os", "version": "1.0.0", "platform": "Linux", "type": "BUILD", "owner": "111122223333", "dateCreated": "2020-09-24T16:58:24.444Z" }, { "arn": "arn:aws:imagebuilder:us-west-2:111122223333:component/update-linux-os/1.0.1", "name": "update-linux-os", "version": "1.0.1", "platform": "Linux", "type": "BUILD", "owner": "111122223333", "dateCreated": "2021-07-10T03:38:46.091Z" } ] }
PowerShell

Usa il Get-EC2IBComponentList cmdlet con Filter parametro e filtro in base al nome.

In questo esempio, filtrate in base al nome del componente Linux che avete creato in Crea un componente personalizzato da AWS Strumenti per PowerShell. Per elencare il componente che hai creato, usa il valore di Name parametro che hai usato con New-EC2IBComponent cmdlet:

Get-EC2IBComponentList -Filter @{Name="name";Values="update-linux-os"}

Il cmdlet restituisce un oggetto per ogni versione del componente. Ogni oggetto include il componente Arn, Name, Version, Platform, Type, Owner, e DateCreated.

In base ai risultati, puoi determinare quale dovrebbe essere la prossima versione.

Crea un componente personalizzato da AWS Strumenti per PowerShell

In questa sezione, imparerai come utilizzare i cmdlet Image Builder in AWS Strumenti per PowerShell per creare un AWSTOE componente dell'applicazione, come segue:

La New-EC2IBComponent Il cmdlet accetta ogni impostazione del componente come parametro separato, quindi non è necessario un file di input JSON. Ogni esempio in questa sezione utilizza gli stessi valori dell'esempio di piattaforma corrispondente in Crea un componente personalizzato da AWS CLI.

Nota

La maggior parte dei nomi dei parametri dei cmdlet corrisponde ai parametri di richiesta dell'operazione API Image Builder, nel caso Pascal. Ad esempio, semanticVersion diventa SemanticVersion, e kmsKeyId diventa KmsKeyId. Il Tag il parametro accetta una tabella hash di chiavi e valori dei tag. Per esaminare i parametri della richiesta API, consulta CreateComponent operazione in Riferimento all'API EC2 Image Builder.

Per creare un AWSTOE componente applicativo da un documento YAML di input, seguite i passaggi corrispondenti alla piattaforma del sistema operativo dell'immagine.

Linux
Archivia il documento relativo al componente dell'applicazione in Amazon S3

Puoi usare un bucket S3 come repository per i tuoi AWSTOE documento sorgente del componente dell'applicazione. Per archiviare il documento del componente, segui questi passaggi:

  • Carica il documento su Amazon S3

    Se il documento è più piccolo di 64 KB, puoi saltare questo passaggio. I documenti di dimensioni pari o superiori a 64 KB devono essere archiviati in Amazon S3.

    Per caricare il documento, esegui Write-S3Object cmdlet:

    Write-S3Object -BucketName amzn-s3-demo-destination-bucket ` -Key my-path/update-linux-os.yaml ` -File update-linux-os.yaml
Crea un componente dal documento YAML

Usa il Uri parametro per fare riferimento a update-linux-os.yaml documento che hai caricato in precedenza.

  • Crea il componente

    Per creare il componente, esegui New-EC2IBComponent cmdlet:

    New-EC2IBComponent -Name update-linux-os ` -SemanticVersion 1.1.2 ` -Description "An example component that updates the Linux operating system" ` -ChangeDescription "Initial version." ` -Platform Linux ` -Uri s3://amzn-s3-demo-destination-bucket/my-path/update-linux-os.yaml ` -KmsKeyId arn:aws:kms:us-west-2:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 ` -Tag @{ "my-tag-key-purpose" = "security-updates" }
Windows
Archivia il documento relativo ai componenti dell'applicazione in Amazon S3

Puoi usare un bucket S3 come repository per i tuoi AWSTOE documento sorgente del componente dell'applicazione. Per archiviare il documento del componente, segui questi passaggi:

  • Carica il documento su Amazon S3

    Se il documento è più piccolo di 64 KB, puoi saltare questo passaggio. I documenti di dimensioni pari o superiori a 64 KB devono essere archiviati in Amazon S3.

    Per caricare il documento, esegui Write-S3Object cmdlet:

    Write-S3Object -BucketName amzn-s3-demo-destination-bucket ` -Key my-path/update-windows-os.yaml ` -File update-windows-os.yaml
Crea un componente dal documento YAML

Usa il Uri parametro per fare riferimento a update-windows-os.yaml documento che hai caricato in precedenza.

  • Crea il componente

    Per creare il componente, esegui New-EC2IBComponent cmdlet:

    New-EC2IBComponent -Name update-windows-os ` -SemanticVersion 1.1.2 ` -Description "An example component that updates the Windows operating system." ` -ChangeDescription "Initial version." ` -Platform Windows ` -Uri s3://amzn-s3-demo-destination-bucket/my-path/update-windows-os.yaml ` -KmsKeyId arn:aws:kms:us-west-2:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 ` -Tag @{ "my-tag-key-purpose" = "security-updates" }
macOS
Archivia il documento relativo ai componenti dell'applicazione in Amazon S3

Puoi usare un bucket S3 come repository per i tuoi AWSTOE documento sorgente del componente dell'applicazione. Per archiviare il documento del componente, segui questi passaggi:

  • Carica il documento su Amazon S3

    Se il documento è più piccolo di 64 KB, puoi saltare questo passaggio. I documenti di dimensioni pari o superiori a 64 KB devono essere archiviati in Amazon S3.

    Per caricare il documento, esegui Write-S3Object cmdlet:

    Write-S3Object -BucketName amzn-s3-demo-destination-bucket ` -Key my-path/wget-macos.yaml ` -File wget-macos.yaml
Crea un componente dal documento YAML

Usa il Uri parametro per fare riferimento a wget-macos.yaml documento che hai caricato in precedenza.

  • Crea il componente

    Per creare il componente, esegui New-EC2IBComponent cmdlet:

    New-EC2IBComponent -Name install-wget-macos-component ` -SemanticVersion 1.1.2 ` -Description "An example component that installs and verifies the wget utility on macOS." ` -ChangeDescription "Initial version." ` -Platform macOS ` -Uri s3://amzn-s3-demo-destination-bucket/my-path/wget-macos.yaml ` -KmsKeyId arn:aws:kms:us-west-2:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 ` -Tag @{ "my-tag-key-purpose" = "install-software" }

Importa uno script per creare un componente

In alcuni scenari, potrebbe essere più semplice iniziare con uno script preesistente. Per questo scenario, è possibile utilizzare il seguente esempio.

Questo esempio utilizza un PowerShell script chiamato admin-config.ps1 che hai già caricato amzn-s3-demo-source-bucket. Attualmente, l'unico formato di componente supportato è SHELL.

AWS CLI

Questo esempio presuppone che tu abbia un file chiamato import-component.json. Il file contiene quanto segue:

{ "name": "my-imported-component", "semanticVersion": "1.0.0", "description": "An example of how to import a component", "changeDescription": "First commit message.", "format": "SHELL", "platform": "Windows", "type": "BUILD", "uri": "s3://amzn-s3-demo-source-bucket/admin-config.ps1", "kmsKeyId": "arn:aws:kms:us-west-2:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222" }

Per creare il componente da uno script importato, eseguite il comando seguente:

aws imagebuilder import-component --cli-input-json file://import-component.json
PowerShell

Questo esempio utilizza gli stessi valori di AWS CLI esempio. Strumenti per PowerShell non accetta un file di input JSON. Invece, ogni chiave JSON è un parametro del cmdlet. Ad esempio, semanticVersion diventa SemanticVersion, e uri diventa Uri.

Per creare il componente da uno script importato, eseguite Import-EC2IBComponent cmdlet:

Import-EC2IBComponent -Name my-imported-component ` -SemanticVersion 1.0.0 ` -Description "An example of how to import a component" ` -ChangeDescription "First commit message." ` -Format SHELL ` -Platform Windows ` -Type BUILD ` -Uri s3://amzn-s3-demo-source-bucket/admin-config.ps1 ` -KmsKeyId arn:aws:kms:us-west-2:111122223333:key/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222

Gestione automatica delle versioni di compilazione

Quando si crea un componente con lo stesso nome e la stessa versione semantica di un componente esistente, Image Builder incrementa automaticamente la versione di compilazione (ad esempio, da /1 a /2, a /3, e così via). Ciò consente di effettuare aggiornamenti iterativi ai componenti senza gestire manualmente i numeri di versione, il che è particolarmente utile in CI/CD pipeline e implementazioni infrastructure-as-code. Se il contenuto del componente è identico alla versione di build precedente, Image Builder restituisce ResourceAlreadyExistsException per evitare che componenti duplicati consumino la quota di servizio.

Utilizzo dei riferimenti di versione

Quando si crea o si recupera un componente, Image Builder fornisce automaticamente agli ARN precostruiti modelli di versione con caratteri jolly nella versione più recenteVersionReferences oggetto. Questi riferimenti semplificano l'utilizzo delle versioni più recenti dei componenti in ricette e pipeline senza dover analizzare manualmente gli ARN.

Scegliete il riferimento alla versione corretto

L'elenco seguente descrive quando utilizzare ogni riferimento di versione:

  • più recenteVersionArn (x.x.x) - Usa sempre la versione del componente più recente in assoluto.

  • più recenteMajorVersionArn (1.x.x): utilizza le versioni secondarie e le patch più recenti all'interno di una versione principale.

  • più recenteMinorVersionArn (1.2.x) - Usa solo la versione della patch più recente.

  • più recentePatchVersionArn (1.2.3) - Fai riferimento a una versione semantica specifica, ma ottieni l'ultima versione di build.