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 |
component |
Mandatory. Indicates a particular component in DevOps. A missing or invalid value causes failure of the stage. Supported value is |
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 |
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:
|
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:
Note: For |
steps |
Mandatory. This section defines a list of steps that needs to be run.
|
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 |
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 |
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