Befehlsspezifikation

Die Befehlsspezifikation enthält Shellbefehle und Einstellungen, die während eines Deployments ausgeführt werden. Die Befehlsspezifikation wird in YAML geschrieben. Der Dateiinhalt kann inline angegeben werden, oder die Spezifikation kann in einem Artifact Registry-Repository gespeichert werden.

Um eine Binärdatei auszuführen, die nicht von Oracle vorinstalliert ist, müssen Sie sie entweder direkt in den Root-Ordner herunterladen oder in den Workspace-Ordner herunterladen und dann vor der Ausführung in den Root-Ordner verschieben.

Die Befehlsspezifikation ist in folgende Abschnitte unterteilt:

Setup der Umgebungsvariablen
Eingabeartefakte
Schritte, die sequenziell ausgeführt werden müssen

Befehlsspezifikationssyntax

version: 0.1
component: command
timeoutInSeconds: 10000
shell: bash
failImmediatelyOnError: true
env:
  variables:
    key: "value"
    key: "value"
  vaultVariables:
    key: "secret-id"
 
inputArtifacts:
  - name: artifact-name
    type: GENERIC_ARTIFACT
    artifactId: "artifact-ocid"
    registryId: OCID of the Artifact Registry
    path: path of the artifact in the Registry
    version: version of the artifact
    location: target-location
  - name: artifact-name
    type: URL
    url: downloadable link
    location: target-location
 
steps:
  - type: Command
    name: step-name
    shell: shellType
    timeoutInSeconds: 650
    failImmediatelyOnError: true
    command: command
    onFailure:
      - type: Command
        command: |
          command
          command
        timeoutInSeconds: 400
 
  - type: Command
    name: step-name
    command: |
      command
      command
      command
    onFailure:
      - type: Command
        command: |
          command
        timeoutInSeconds: 400

Befehlsspezifikationsparameter

Im Folgenden sind die Parameter der Befehlsspezifikation und die zugehörigen Details aufgeführt:


Parameter	Beschreibung
`version`	Obligatorisch. Gibt die Version der Befehlsspezifikation an. Eine fehlende oder ungültige Version führt zu einem Fehler in der Shellphase. Der unterstützte Wert lautet `0.1`.
`component`	Obligatorisch. Gibt eine bestimmte Komponente in DevOps an. Ein fehlender oder ungültiger Wert führt zu einem Fehler in der Phase. Der unterstützte Wert lautet `command`.
`timeoutInSeconds`	Optional. Gibt den Timeout für die gesamte Befehlsspezifikationsdatei an. Jeder "Schritt" kann optional auch einen eigenen Timeoutwert haben. Wenn kein Wert angegeben ist, wird der Standardwert "8 Stunden" verwendet. Der maximal zulässige Wert beträgt 8 Stunden.
`shell`	Optional. Gibt die Shell an, die auf der globalen Ebene der Befehlsspezifikation verwendet werden soll. Der Wert kann optional auf Schrittebene überschrieben werden. Zulässige Werte sind `/bin/sh` und `bash`. Wenn kein Wert angegeben ist, wird der Standardwert `bash` verwendet.
`failImmediatelyOnError`	Optional. Gibt an, ob das Deployment fortgesetzt werden muss, wenn ein Befehl im Schritt mit einem Exit-Wert ungleich null nicht erfolgreich verläuft. Wenn kein Wert angegeben ist, lautet der Standardwert `false`, und der Schritt wird fortgesetzt. Zulässige Werte sind `true` und `false`. OCI empfiehlt, den Wert dieses Attributs auf `true` zu setzen.
`env`	Optional. Sie können benutzerdefinierte Variablen definieren. Drei Variablentypen werden unterstützt: env/variables: Optional. Der Schlüssel muss eine Zeichenfolge und mit POSIX-Umgebungsvariablen konform sein. Der Wert kann eine beliebige Zeichenfolge sein. Der Geltungsbereich dieser Variablen ist die Ausführung der Befehlsspezifikationsdatei. Eine Änderung des Variablenwertes ist in den nachfolgenden Schritten sichtbar. Diese Variablen sind als Umgebungsvariablen für alle Schritte innerhalb der Befehlsspezifikationsdatei verfügbar. Wenn der Wert der Variablen Zeilenvorschub- (\n) oder Zeilenschaltungszeichen (\r) enthält, werden diese in den folgenden Schritten durch Leerzeichen ersetzt. env/vaultVariables: Optional. Der Schlüssel muss eine Zeichenfolge und mit POSIX-Umgebungsvariablen konform sein. Der Wert muss eine OCID des Secrets aus dem Vault sein. Der Vault und die Pipeline müssen demselben Mandanten angehören. Der Mandant muss über die entsprechende Policy verfügen, damit Deployment-Pipelineressourcen auf das Secret zugreifen können. Der Geltungsbereich dieser Variablen ist die Ausführung der Befehlsspezifikationsdatei und steht in allen Schritten in der Datei zur Verfügung. Die Werte für diese Variablen werden aus dem Vault abgerufen und als Umgebungsvariablen für alle Schritte in der Befehlsspezifikationsdatei zur Verfügung gestellt. env/exportedVariables: Optional. Eine Liste der Variablen kann hier deklariert werden. Der Name der Variablen muss eine Zeichenfolge und mit POSIX-Umgebungsvariablen konform sein. Der Wert kann in einem der Schritte in der Befehlsspezifikationsdatei zugewiesen werden. Der Geltungsbereich dieser Variablen ist die Deployment-Pipeline. Exportierte Variablen sind nur in Shellphasen dieser Pipeline verfügbar.
`inputArtifacts`	Optional. Wird verwendet, um eine Liste der Eingabeartefakte zu definieren, die für die Ausführung der aktuellen Shellphase erforderlich sind. Unterstützt generische Artefakte aus Artifact Registry. Folgende Parameter sind verfügbar: *inputArtifacts//url: Optionale Option. Die externe herunterladbare HTTP-URL des Eingabeartefakts muss angegeben werden. Die URL muss öffentlich verfügbar sein. Die Authentifizierung/Autorisierung wird derzeit nicht unterstützt. inputArtifacts//name: Erforderlich. Mit diesem Namen wird auf die Artefakte in der Befehlsausführung verwiesen. inputArtifacts//location: Erforderlich. Ein Zielpfad des lokalen Dateisystems, in den das Eingabeartefakt heruntergeladen werden muss. Der Pfad kann mit einer der folgenden Methoden angegeben werden: `${OCI_PRIMARY_SOURCE_DIR}/pom.xml` `${OCI_WORKSPACE_DIR}/[source-name]/pom.xml` `/workspace/[source-name]/pom.xml` Relativer Pfad vom Projekt-Home, `pom.xml` Mit jedem der Werte wird das Eingabeartefakt mit dem Dateinamen `pom.xml` in das primäre Quell-Home-Verzeichnis heruntergeladen. Der Speicherort unterstützt keine `exportedVariables` oder Pipelinevariablen. inputArtifacts//type: Erforderlich. Der Typ des Eingabeartefakts, das heruntergeladen werden muss. Zulässige Werte sind `URL` und `GENERIC_ARTIFACT`. inputArtifacts//artifactld*: Erforderlich. Die OCID des Artefakts. Wenn Sie die OCID angegeben haben, ignoriert die Deployment-Pipeline registryId, Pfad und Version. inputArtifacts/: Erforderlich. Die OCID der Artefakt-Registry. *inputArtifacts//path: Obligatorisch. Der Zielpfad des Artefakts. inputArtifacts//version: Obligatorisch. Die Version des Artefakts. Hinweis:* Für den Eingabeartefakttyp `GENERIC_ARTIFACT` können Sie als obligatorischen Parameter entweder die OCID des Artefakts oder eine Kombination aus Registry-ID, Pfad und Artefaktversion angeben.
`steps`	Obligatorisch. In diesem Abschnitt wird eine Liste der Schritte definiert, die ausgeführt werden müssen. *steps//type: Obligatorisch. Gibt den Schritttyp an. Unterstützt die folgenden Werte: `Command` steps//name*: Optional. Ein benutzerfreundlicher Name für den Schritt.

Schritttypen

Befehl


Attributname	Beschreibung
`command`	Sowohl einzeilige als auch mehrzeilige Befehle werden unterstützt. Alle in einem Schritt angegebenen Befehle werden in derselben Shell-Session ausgeführt. Basierend auf dem Wert `steps/*/shell` kann es sich um Shell- oder Bash-Befehle handeln. Fast Fail ist nicht aktiviert. Damit der Schritt erfolgreich verläuft, wird die Ausgabe des letzten Befehls in einem Schritt berücksichtigt. Wenn der Exitcode des letzten Befehls 0 ist, wird der Schritt als erfolgreich betrachtet.
`timeoutInSeconds` (Optional)	Gibt den Timeout für den Schritt an. Ist kein Wert angegeben, wird der Wert vom globalen `timeoutInSeconds`-Parameter übernommen. Der maximal zulässige Wert beträgt 8 Stunden.
`shell` (Optional)	Gibt den Shell-Typ des aktuellen Schritts an. Ist kein Wert angegeben, wird der Wert vom globalen `shell`-Parameter übernommen. Zulässige Werte sind `/bin/sh` und `shell`.
`onFailure` (Optional)	Eine Liste der Schritte, die bei einem Fehler ausgeführt werden müssen, damit die Shellphase ordnungsgemäß beendet wird. Diese Schritte werden ausgeführt, wenn der entsprechende Schritt nicht erfolgreich verläuft. Nach der Ausführung wird die Befehlsspezifikation beendet. Die Bearbeitung des Fehlers wirkt sich nicht auf den Status der Shellphase aus. Wenn einer der Schritte nicht erfolgreich verläuft, verbleibt die Shellphase im Status `failed`, obwohl der Fehler mit dem `onFailure`-Block bearbeitet wurde.
`failImmediatelyOnError` (Optional)	Gibt an, ob das Deployment fortgesetzt werden muss, wenn ein Befehl im Schritt mit einem Exit-Wert ungleich null nicht erfolgreich verläuft. Wenn kein Wert angegeben ist, lautet der Standardwert `false`, und der Schritt wird fortgesetzt. Zulässige Werte sind `true` und `false`. OCI empfiehlt, den Wert dieses Attributs auf `true` zu setzen. Der unter `steps` definierte Attributwert `failImmediatelyOnError` hat Vorrang vor demselben Attributwert, der außerhalb von `steps` definiert wurde.

Vordefinierte Systemvariablen

DevOps stellt vordefinierte Systemvariablen mit Standardwerten bereit, die Sie in der Befehlsspezifikation verwenden können.


Variable	Beschreibung
`OCI_DEPLOYMENT_ID`	Die OCID des aktuellen Deployments.
`OCI_PIPELINE_ID`	Die OCID der aktuellen Deployment-Pipeline.
`OCI_RESOURCE_PRINCIPAL_RPST`	Resource Principal-Token.
`OCI_RESOURCE_PRINCIPAL_VERSION`	Resource Principal-Version.
`OCI_CLI_AUTH`	Vorkonfigurierte Authentifizierung der OCI-CLI zur Verwendung des Resource Principals.
`OCI_RESOURCE_PRINCIPAL_REGION`	Region des Resource Principals.
`OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM`	Private-Key-Pfad des Resource Principals.

Beispiel einer Befehlsspezifikation

Beispiel: Erstellen Sie einen OKE-Namespace.