Verwenden von privaten Erweiterungen in CloudFormation

Private Erweiterungen sind die Erweiterungen, die Sie explizit für die Verwendung in Ihrem AWS-Konto registriert haben.

Es gibt zwei Arten von Erweiterungen:

• Aktivierte private Erweiterungen – Sind die lokalen Kopien von Erweiterungen von Drittanbietern, die Sie für Ihr Konto und Ihre Region aktiviert haben. Wenn Sie eine öffentliche Erweiterung eines Drittanbieters aktivieren, CloudFormation erstellt eine lokale Kopie dieser Erweiterung in der Registrierung Ihres Kontos.

• Registrierte private Erweiterungen — Sie können auch private Erweiterungen aktivieren, die nicht in der öffentlichen CloudFormation Registrierung aufgeführt sind. Dies können Erweiterungen sein, die Sie selbst erstellt haben, oder solche, die von Ihrer Organisation oder einem anderen Drittanbieter für Sie freigegeben wurden. Um eine solche private Erweiterung in Ihrem Konto zu verwenden, müssen Sie sie zuerst registrieren. Durch die Registrierung der Erweiterung wird eine Kopie der Erweiterung in die CloudFormation Registrierung in Ihrem Konto hochgeladen und aktiviert.

Jede Verwendung von privaten Erweiterungen in Ihrem Konto entspricht der Verwendung in einer Sandbox-Umgebung. Dies liegt daran, dass Erweiterungen versioniert und das Bereitstellungsverhalten versionsspezifisch ist, was bedeutet, dass sich private Erweiterungen genauso verhalten, als wären sie öffentlich gemacht worden.

Anmerkung

Private Erweiterungen und aktivierte öffentliche Erweiterungen von Drittanbietern können Ereignis-Handler implementieren, die während Erstellungs-, Lese-, Aktualisierungs-, Listen- und Löschvorgängen ausgeführt werden. Aus diesem Grund fallen Gebühren für Ihr Konto an, wenn Sie diese Erweiterungen in Ihren CloudFormation Stacks verwenden. Dies wird zusätzlich zu den für die erstellten Ressourcen anfallenden Gebühren berechnet. Weitere Informationen finden Sie unter AWS CloudFormation Preise.

Informationen zur Entwicklung eigener privater Erweiterungen finden Sie im CloudFormation Command Line Interface User Guide.

Registrieren privater Erweiterungen

Um private Erweiterungen zu verwenden, die nicht in der CloudFormation Registrierung aufgeführt sind — entweder solche, die Sie selbst entwickelt haben, oder solche, die mit Ihnen geteilt wurden —, müssen Sie sie zunächst in den Konten und Regionen registrieren CloudFormation, in denen Sie sie verwenden möchten. Durch die Registrierung der Erweiterung wird eine Kopie der Erweiterung in die CloudFormation Registrierung in Ihrem Konto hochgeladen und aktiviert. Sobald Sie eine private Erweiterung registriert haben, wird sie in der CloudFormation Registrierung für dieses Konto und diese Region angezeigt, und Sie können sie in Ihren Stack-Vorlagen verwenden.

Sie können eine Erweiterung mit dem Befehl register-type der oder mit dem AWS CLIsubmit Befehl der CloudFormation CLI registrieren.

Informationen zur Registrierung einer privaten Erweiterung mit der CloudFormation CLI finden Sie unter Registrieren von Erweiterungen im CloudFormation CLI-Benutzerhandbuch.

IAM-Berechtigungen zum Registrieren einer privaten Erweiterung

Als Teil der Registrierung einer privaten Erweiterung geben Sie einen Amazon-S3-Bucket an, der das Erweiterungs-Projektpaket enthält. Dieses Paket enthält alle Quelldateien, die für die Erweiterung erforderlich sind, die Sie registrieren möchten. Der Benutzer, der die Erweiterung registriert, muss auf das Projektpaket in diesem Amazon-S3-Bucket zugreifen können. Das heißt, der Benutzer benötigt GetObjectBerechtigungen für das Erweiterungspaket.

Dies gilt unabhängig davon, ob Sie entweder den Befehl register-type der oder den AWS CLIsubmit Befehl der CloudFormation CLI verwenden.

Weitere Informationen finden Sie unter Aktionen, Ressourcen und Bedingungsschlüssel für Amazon S3 im Benutzerhandbuch für AWS Identity and Access Management .

Registrieren von Erweiterungen

Registrieren Sie Ihre Erweiterung in der AWS CloudFormation Registrierung, damit sie verwendet werden kann.

Um einen Hook mit dem zu registrieren AWS CLI

Registrieren Sie Ihren Hook bei CloudFormation, damit er in der AWS CloudFormation Registry verwendet werden kann.

1. (Optional) Konfigurieren Sie Ihren AWS-Region Standardnamen aufus-west-2, indem Sie den configure Vorgang abschicken.

   aws configure
   AWS Access Key ID [None]: <Your Access Key ID>
   AWS Secret Access Key [None]: <Your Secret Key>
   Default region name [None]: us-west-2
   Default output format [None]: json

2. (Optional) Der folgende Befehl erstellt und verpackt Ihr Hook-Projekt, ohne es zu registrieren.

   $ cfn submit --dry-run

3. Registrieren Sie Ihren Hook mit der CloudFormation CLIcfn submit.

   cfn submit --set-default

   Der Befehl gibt den folgenden Befehl zurück.

   {‘ProgressStatus’: ‘COMPLETE’}

   Ergebnisse: Sie haben Ihren Hook erfolgreich registriert.

Um einen Ressourcentyp mit dem zu registrieren AWS CLI

Registrieren Sie Ihren Ressourcentyp bei CloudFormation, damit er in der AWS CloudFormation Registrierung verwendet werden kann.

1. Suchen Sie den Amazon S3 Bucket, der das Projektpaket für die private Erweiterung enthält, die Sie in Ihrem Konto registrieren möchten.

2. Verwenden Sie den Befehl register-type, um die Erweiterung in Ihrem Konto zu registrieren:

   RegisterType ist ein asynchroner Vorgang und gibt ein Registrierungs-Token zurück, mit dem Sie den Fortschritt Ihrer Registrierungs-Anforderung verfolgen können.

   Anmerkung

   Wenn Ihre Erweiterung im Rahmen ihrer Funktionalität AWS APIs aufruft, müssen Sie eine IAM-Ausführungsrolle erstellen, die die erforderlichen Berechtigungen zum Aufrufen dieser AWS APIs enthält, und diese Ausführungsrolle in Ihrem Konto bereitstellen. Anschließend können Sie diese Ausführungsrolle mithilfe des --execution-role-arn Parameters angeben. CloudFormation geht dann davon aus, dass diese Ausführungsrolle Ihrem Ressourcentyp die entsprechenden Anmeldeinformationen zur Verfügung stellt.

   Beispiel: Der folgende Befehl registriert den My::Resource::Example-Ressourcentyp im aktuellen AWS-Konto:

   aws cloudformation register-type --type-name My::Resource::Example --schema-handler-package [s3 object path] --type RESOURCE                
   {
       "RegistrationToken": "f5525280-104e-4d35-bef5-8f1fexample"
   }

3. Optional: Verwenden Sie das Registrierungstoken mit dem describe-type-registration-Befehl, um den Fortschritt Ihrer Registrierungsanforderung zu verfolgen.

   Wenn die Registrierungsanfrage CloudFormation abgeschlossen ist, wird der Fortschrittsstatus der Anfrage auf festgelegtCOMPLETE.

   Im folgenden Beispiel wird das vom oben genannten describe-type-registration Befehl zurückgegebene Registrierungs-Token verwendet, um Registrierungs-Statusinformationen zurückzugeben.

   aws cloudformation describe-type-registration --registration-token f5525280-104e-4d35-bef5-8f1fexample
   {
       "ProgressStatus": "COMPLETE",
       "TypeArn": "arn:aws:cloudformation:us-east-1:012345678910:type/resource/My-Resource-Example",
       "Description": "Deployment is currently in DEPLOY_STAGE of status COMPLETED; ",
       "TypeVersionArn": "arn:aws:cloudformation:us-east-1:111122223333:type/resource/My-Resource-Example/00000001"
   }

Konfigurieren von Erweiterungen auf Konto-Ebene

Eine Erweiterung kann Konfigurations-Eigenschaften enthalten, die für alle Instances der Erweiterung für ein bestimmtes Konto und eine Region gelten sollen. Der Autor der Erweiterung definiert diese in der Definitions-Konfiguration der Erweiterung. Wenn die Konfigurations-Definition der Erweiterung erforderliche Eigenschaften enthält, müssen Sie diese Eigenschaften angeben, bevor Sie die Erweiterung in Ihrem Konto und Ihrer Region verwenden können.

Anmerkung

Wenn Ihre Typkonfiguration dynamische Verweise auf Werte enthält, die in AWS Systems Manager oder gespeichert sind AWS Secrets Manager, muss jede Rolle, die zur Bereitstellung des Typs verwendet wird (z. B. beim Erstellen oder Aktualisieren eines Stacks), über die entsprechenden Berechtigungen zum Abrufen dieses Werts verfügen. Das heißt:

• Wenn die Typkonfiguration einen im AWS Systems Manager Parameter Store gespeicherten Parameter enthält, muss der Benutzer oder die Rolle, mit der der Typ bereitgestellt wurde, über Aufrufberechtigungen verfügen GetParameter.

• Wenn die Typkonfiguration einen geheimen Schlüssel enthält, der in gespeichert ist AWS Secrets Manager, muss der Benutzer oder die Rolle, mit der der Typ bereitgestellt wurde, über Aufrufberechtigungen verfügen GetSecretValue.

Weitere Informationen zu dynamischen Referenzen finden Sie unter Verwenden von dynamischen Verweisen zum Angeben von Vorlagenwerten.

Weitere Informationen dazu, wie Konfigurationsdefinitionen bei der Entwicklung einer Erweiterung definiert werden, finden Sie unter Definieren der Konfiguration einer Erweiterung auf Kontoebene im CloudFormation Benutzerhandbuch für die Entwicklung von Erweiterungen.

So zeigen Sie die aktuellen Konfigurationsdaten für eine Erweiterung in der Konsole an CloudFormation

1. Verwenden Sie die CloudFormation Registrierung, um die Erweiterung zu finden.

2. Wählen Sie die Erweiterung aus, um die Details der Erweiterung anzuzeigen.

3. Wählen Sie auf der Seite zu den Erweiterungsdetails die Registerkarte Configuration (Konfiguration).

4. Erweitern Sie die Registerkarte Configuration schema (Schema der Konfiguration), um das für die Erweiterung definierte Konfigurationsschema anzuzeigen.

5. Erweitern Sie die Registerkarte Configuration (Konfiguration), um die aktuelle Konfiguration anzuzeigen, die Sie für diese Erweiterung festgelegt haben.

Um die aktuellen Konfigurationsdaten für eine Erweiterung in der AWS CLI

• Verwenden Sie den Befehl describe-type, um detaillierte Informationen über die Erweiterung zurückzugeben. Das ConfigurationSchema-Element der Ausgabe enthält die aktuelle Konfigurations-Definition der Erweiterung in einer bestimmten Region.

  Als alternative Vorgehensweise verwenden Sie den Befehl batch-describe-type-configurations, um Konfigurationsdaten über mehrere Erweiterungen zurückzugeben.

So geben Sie Konfigurations-Eigenschaften für Erweiterungstypen an

So geben Sie die Konfigurationseigenschaften für eine Erweiterung mithilfe der CloudFormation Konsole an

1. Verwenden Sie die CloudFormation Registrierung, um die Erweiterung in den aktivierten Erweiterungen Ihres Kontos zu finden.

2. Wählen Sie die Erweiterung aus, um die Erweiterungs-Details anzuzeigen.

3. Wählen Sie auf der Seite mit den Erweiterungs-Details auf der Registerkarte Configuration (Konfiguration) die Option Edit configuration (Konfiguration bearbeiten).

   Wählen Sie alternativ unter Actions (Aktionen) die Option Edit (Bearbeiten) und dann Edit configuration (Konfiguration bearbeiten).

   CloudFormation zeigt die Seite Erweiterung konfigurieren an. Stellen Sie sicher, dass View configuration schema (Konfigurationsschema anzeigen) aktiviert ist, um das aktuelle Konfigurations-Definitionsschema der Erweiterung anzuzeigen.

4. Geben Sie im Textfeld Configuration JSON eine JSON-Zeichenfolge ein, die das Konfigurationsschema darstellt, das Sie für diese Erweiterung festlegen möchten. Es muss mit dem Schema validiert werden, das in Configuration schema (Konfigurationsschema) angegeben ist.

5. Wählen Sie Configure extension (Erweiterung konfigurieren) aus.

Um Konfigurationseigenschaften für eine Erweiterung anzugeben, verwenden Sie AWS CLI

• Verwenden Sie set-type-configuration, um die Konfiguration anzugeben, die mit der Erweiterung in Ihrem Konto und Ihrer Region verwendet werden soll.

  Die JSON, die Sie für --configuration übergeben, muss anhand des Konfigurations-Definitionsschemas der Erweiterung validieren. Es folgt ein Beispiel für einen set-type-configuration-Befehl, der die Konfiguration festlegt.

  aws cloudformation set-type-configuration \
      --region us-west-2 \
      --type RESOURCE \
      --type-name My::Resource::Example \
      --configuration-alias default \
      --configuration "{"CredentialKey": "testUserCredential"}"

Angeben einer zu verwendenden Version einer privaten Erweiterung mit dem AWS CLI

Im Laufe der Zeit registrieren Sie möglicherweise mehrere Versionen derselben Erweiterung. Sie können angeben, welche Version der Erweiterung Sie für CloudFormation Operationen verwenden möchten.

So geben Sie eine Version einer Erweiterung an

Verwenden Sie den set-type-default-version Befehl, um anzugeben, welche Version der Erweiterung für CloudFormation Operationen in Ihrem Konto verwendet werden soll.

Mit dem folgenden Befehl wird beispielsweise die Standardversion des My::Resource::Example-Ressourcentyps für das aktuelle Konto auf 00000003 festgelegt.

aws cloudformation set-type-default-version \
  --type RESOURCE \
  --type-name My::Resource::Example \
  --version-id 00000003

So geben Sie die Standard-Hook-Version an

Um die Standardversion Ihres Hooks in Ihrem Konto anzugeben, verwenden Sie den Befehl set-type-default-version und geben Sie den Typ, den Typnamen und die Versions-ID an.

aws cloudformation set-type-default-version \
    --type HOOK \
    --type-name MyCompany::Testing::MyTestHook \
    --version-id 00000003