Command Specification

The command specification contains shell commands and settings that are run during a deployment. The command specification is written in YAML. The file content can be specified inline or the spec can be stored in an Artifact Registry repository.

To run any binary file that's not pre-installed by Oracle, you must either download it to the root folder directly, or download to the workspace folder, and then move it to the root folder before executing.

The command specification is organized into the following sections:

  • Setup of environment variables.
  • Input artifacts.
  • Steps to run in sequence.

Command Specification Syntax

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

Command Specification Parameters

Following are the command specification parameters and their details:

Parameter Description
version Mandatory. Indicates the command specification version. A missing or invalid version causes Shell stage failure.

Supported value is 0.1.

component Mandatory. Indicates a particular component in DevOps. A missing or invalid value causes failure of the stage.

Supported value is command.

timeoutInSeconds Optional. Specifies the timeout for the whole command specification file. Each 'step' can also optionally have its own timeout value.

If a value isn't specified, then the default value of 8 hours is used. The maximum allowed value is 8 hours.

shell Optional. Specifies the shell to be used at the command specification global level. The value can be optionally overridden at the 'step' level.

Allowed values are /bin/sh and bash. If not specified, then the default value of bash is used.

failImmediatelyOnError Optional. Specifies whether the deployment must continue if any command in the step fails with a nonzero exit value. If not specified, then the default value is false and the step continues. Allowed values are true and false. OCI recommends setting the value of this attribute to true.
env

Optional. You can define custom variables. Three types of variables are supported:

  • env/variables: Optional. The key must be a string and POSIX environment variable compliant. The value can be any string. The scope of this variable is the execution of the command specification file. Any change to the value of the variable is visible in the subsequent steps. These variables are available as environment variables for all the steps inside the command specification file.

    If the value of the variable contains new line(\n) or carriage return(\r) character, then they're replaced with space in the subsequent steps.

  • env/vaultVariables: Optional. The key must be a string and POSIX environment variable compliant. The value must be an OCID of the secret from the vault. The vault and pipeline must be of the same tenancy. The tenancy must have an appropriate policy to allow deployment pipeline resources to access the secret.

    The scope of this variable is the execution of the command specification file and is available to all the steps in the file. The value for these variables is retrieved from the vault and made available as environment variables for all the steps inside the command specification file.

  • env/exportedVariables: Optional. A list of variables can be declared here. The name of the variable must be a string and POSIX environment variable compliant. The value can be assigned in any of the steps inside the command specification file. The scope of this variable is the deployment pipeline. Any exported variable is available only in Shell stages of the same pipeline.
inputArtifacts

Optional. Used to define a list of input artifacts that 's required for running the current Shell stage.

Supports generic artifacts from Artifact Registry.

The parameters are as follows:

  • inputArtifacts/*/url: Optional. The input artifact external downloadable HTTP URL must be provided. The URL must be publicly available. Currently authentication/authorization isn't supported.
  • inputArtifacts/*/name: Mandatory. This name is used to refer the artifacts in command execution.
  • inputArtifacts/*/location: Mandatory. A destination path of the local file system where the input artifact needs to be downloaded. The path can be specified in one of these methods:
    • ${OCI_PRIMARY_SOURCE_DIR}/pom.xml
    • ${OCI_WORKSPACE_DIR}/[source-name]/pom.xml
    • /workspace/[source-name]/pom.xml
    • Relative path from project home, pom.xml

    With any one of the values, the input artifact is downloaded to the primary source home directory with a file name, pom.xml.

    Location does not support exportedVariables or pipeline variables.

  • inputArtifacts/*/type: Mandatory. The type of the input artifact that has to be downloaded. Allowed values are URL and GENERIC_ARTIFACT.
  • inputArtifacts/*/artifactld: Mandatory. The OCID of the artifact. If you have provided the OCID, then the deployment pipeline ignores the registryId, path, and version.
  • inputArtifacts/*/registryld: Mandatory. The OCID of the Artifact Registry.
  • inputArtifacts/*/path: Mandatory. The destination path of the artifact.
  • inputArtifacts/*/version: Mandatory. The version of the artifact.

Note: For GENERIC_ARTIFACT type of input artifact, you can provide as a mandatory parameter either OCID of the artifact or a combination of registry ID, path, and artifact version.

steps

Mandatory. This section defines a list of steps that needs to be run.

  • steps/*/type: Mandatory. Specifies the type of the step. Supports the following values: Command
  • steps/*/name: Optional. A user-friendly name for the step.

Step Types

Command

Attribute name Description
command Both single line and multiple line commands are supported. All the commands specified in one step are run in the same shell session. Based on the steps/*/shell value, commands can either be shell or bash.

Fail fast isn't enabled. For the step to be successful, output of the last command in a step is considered. If the last command exit code is 0, then the step is considered as successful.

timeoutInSeconds (Optional) Specifies the timeout for the step. If not provided, then the value is inherited from the global timeoutInSeconds parameter. The maximum allowed value is 8 hours.
shell (Optional) Specifies the shell type of the current step. If not specified, then the value is inherited from the global shell parameter. Allowed values are /bin/sh and shell.
onFailure (Optional) A list of steps that must be run on failure to gracefully exit the Shell stage. Run if the corresponding step fails, and after execution, the command specification is exited.

Handling the failure doesn't affect the status of the Shell stage. If any one of the steps fails, then the Shell stage status remains failed, although handled using the onFailure block.

failImmediatelyOnError (Optional) Specifies whether the deployment must continue if any command in the step fails with a nonzero exit value. If not specified, then the default value is false and the step continues. Allowed values are true and false. OCI recommends setting the value of this attribute to true.

The failImmediatelyOnError attribute value defined under steps takes precedence over the same attribute value defined outside the steps.

Predefined System Variables

DevOps provides a set of predefined system variables with default values that you can use in the command specification.

Variable Description
OCI_DEPLOYMENT_ID The OCID of the current deployment.
OCI_PIPELINE_ID The OCID of the current deployment pipeline.
OCI_RESOURCE_PRINCIPAL_RPST Resource principal token.
OCI_RESOURCE_PRINCIPAL_VERSION Resource principal version.
OCI_CLI_AUTH Preconfigured OCI CLI AUTH to use resource principal.
OCI_RESOURCE_PRINCIPAL_REGION Resource principal region.
OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM Resource principal private key path.

Command Specification Example

Example: Create an OKE namespace.

version: 0.1
component: command
timeoutInSeconds: 6000
shell: bash

steps:
  - type: Command
    timeoutInSeconds: 600
    name: "Setup kube config and get nodes"
    command: |
      oci ce cluster create-kubeconfig --cluster-id ${clusterid} --file $HOME/.kube/config --region us-ashburn-1 --token-version 2.0.0  --kube-endpoint ${endpoint}
      kubectl get nodes
    onFailure:
      - type: Command
        command: |
          echo "Failed to set up kube config and get nodes"
        timeoutInSeconds: 60