Oracle Cloud Infrastructure Documentation

Deployment Configuration File

The deployment configuration file defines the artifacts to be downloaded to the instance and the location where the artifacts must be copied. The configuration file also specifies the sequence of commands for deployment.

The configuration file is written in YAML. The file can be defined inline or provided as a generic artifact reference during instance group deployment.

DevOps admins can use the deployment configuration file for the following actions:

  • Specify application packages and their locations for storing in the target compute instance.
  • Specify the steps required to deploy an application.
  • Specify user-defined or built-in environment variables required for deployment.

Deployment Configuration File Structure

Following is the basic structure of the deployment configuration file:

{
version:     
component:   
env: 
    variables:        
timeoutInSeconds:  
files:  
  - source:
    destination:                              
steps:                              
  - stepType: Command 
    name:
    command:
    runAs:
    timeoutInSeconds:
  - stepType: Command 
}

Following are the deployment configuration parameters and their details:

Parameter Description
version Version number of the specification file. Value must be 1.0.
component Component value. The only supported value is deployment.
shell Optional. Specifies the shell to be used at the deployment specification global level. The value can be overridden at the 'step' level. Allowed values are /bin/sh and bash. If not specified, then the default value bash is used.
env: variables

User-defined environment variables that are available to the executables or the bash command that run as part of the deployment.

Examples: key1: static-value, key2: ${PASSED_FROM_PIPELINE}

Built-in variables can also be used. To avoid conflict, built-in variables are prefixed with OCI_DEVOPS.

Built-in variables are:

  • OCI_DEVOPS_PIPELINE_ID
  • OCI_DEVOPS_STAGE_ID
  • OCI_DEVOPS_DEPLOYMENT_ID

env is an optional parameter.
env: vaultVariables Optional. The key must be a string and POSIX environment variable compliant. The value must be an Oracle Cloud Identifier (OCID) of the secret from the vault. The vault and deployment 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 deployment 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 deployment specification file.
files

Specifies the artifacts defined in the deployment pipeline that must be copied and the target compute instance location to copy them to. This parameter is optional.

The configured user, ocarun by default owns the specified directory, and must have write and execute permissions (chmod u+wrx). If the destination folder doesn't exist, then DevOps deployment creates it. To allow that, ocarun (or the configured user) must have write and execute permissions for the parent directory of the specified destination directory.

For example, if you assign the destination directory in the deployment configuration file as /var/services/accountService, then you have to provide write and execute permissions to the configured user for /var/services, and execute permission for /var.
files: source

Specifies the source location of the artifacts. The source can refer to a file or folder. If the source is a file, then that file is copied to the folder defined in the destination. If a folder, then all the contents of that folder are copied to the destination. The source uses relative path, whose root is the root folder of one or more artifacts.

Specify the complete name of the artifact, including the file type extension. For example, if the file in the source is test.sh, then the artifact path must be test.sh or folder-name/test.sh if the file is in a folder.

For example, if the general artifact specifies a single file, run.sh, then this file is downloaded to the root (/) folder in the source. If the general artifact is an archive, for example, app_pkg.zip, then the root of the archive content is the root folder.
files: destination Specifies the target folder where the source file or folder must be copied. OCI DevOps recommends considering the destination as a staging directory for the production code, as the destination directory content is overwritten during every deployment.

In the following deployment spec example, two directories are mentioned. The destination directory is /var/ocarun_staging/app1_staging_folder and the production directory is var/ocarun_prod/main_app.
steps Specifies the list of steps that are run sequentially during the deployment. Each step runs as a different process on the instance. All the specified built-in and user-defined environment variables are passed to the process.
steps: name User-defined name for the step.
steps: command

Shell command or shell executable.

If the files parameter is specified in the configuration file, then the location path for the executable is an absolute path, for example /genericArtifactDemo/start.sh. If the files parameter is not specified, then the relative path is used to specify the location of the executable. The relative path refers to the working folder of the deployment. The artifacts are downloaded and extracted to the current working folder of the deployment.

Both single 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 is not 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. Multiline command works like a bash script. If you want to fail fast for multiline command, then specify the multiline command with (for bash script) set -e \n <rest of the commands> to ensure that the script exits on the first command that fails.

For example, if you specify the command, wrongcommand \n /usr/bin/sudo -n -u root -E /home/opc/scripts/stop.sh \n echo \"Done\" as set -e \n wrongcommand \n /usr/bin/sudo -n -u root -E /home/opc/scripts/stop.sh \n echo \"Done\", then the script exits on wrongcommand.
steps: runAs Run the step as the specified user. By default all steps are run as the ocarun user.
steps: timeoutInSeconds Specifies the timeout period to finish a step.
steps: 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.
steps: onFailure A list of steps that must be run on failure to gracefully exit the deployment stage. Commands under the onFailure section are executed only if the corresponding step fails, and after execution, the deployment specification is exited. Handling the failure does not affect the status of the deployment stage. If any one of the steps fails, then the deployment stage status remains failed.

Following is an example of a deployment configuration file: 

version: 1.0
component: deployment
runAs: ocarun
env: 
  variables: 
    version: ${appVersion}
  vaultVariables:
    SECRET_ID: "OCID of the secret in the vault"    
files: 
  - source: /
    destination: /var/ocarun_staging/app1_staging_folder
steps: 
  - stepType: Command
    name: Validate Variables
    command: echo "Version = ${version}:  Secret = ${SECRET_ID}"
    timeoutInSeconds: 60
  - stepType: Command
    name: Stop currently-running application
    command: cd /var/ocarun_prod/main_app; ./stop.sh
    timeoutInSeconds: 600
  - stepType: Command
    name: Clean old version of source code in prod directory
    command: echo "Perform suitable cleanup"
    timeoutInSeconds: 600
  - stepType: Command
    name: Copy new version of source code from staging directory to prod directory
    command: cp -R /var/ocarun_staging/app1_staging_folder/main_app /var/ocarun_prod/
    timeoutInSeconds: 600
  - stepType: Command
    name: Install application
    command: cd /var/ocarun_prod/main_app; ./install.sh
    timeoutInSeconds: 600
  - stepType: Command
    name: Run application
    command: cd /var/ocarun_prod/main_app; ./start.sh
    timeoutInSeconds: 600

Example of a cloud-init file to setup the two directories (staging and production): 

#cloud-config
users:
  - default
  - name: ocarun
    sudo: ALL=(ALL) NOPASSWD:ALL

# Create two directories, one for staging and one for production.
runcmd:
  - [mkdir, -p, /var/ocarun_staging]
  - [mkdir, -p, /var/ocarun_prod]
  - [chown, ocarun, /var/ocarun_staging]
  - [chown, ocarun, /var/ocarun_prod]

Example to understand multiple entries for source and destination:

version: 1.0
component: deployment
runAs: root
shell: bash
env:
  variables:
    version: ${appVersion}
  vaultVariables:
    docker_registry_password : <secret-ocid>  
files:
  # This section is to define how the files in the artifact is put on the compute instance.
  # Multiple entires are supported using a separate source destination section for every entry.
  - source: /
    destination: /genericArtifactDemo
  - source: /tmp/file1
    destination: /var/applicationPath/someDir1
  - source: /tmp/file2
    destination: /var/applicationPath/someDir2  
steps:
  # This section is to define the scripts that each step runs on the instance after file copy.
  - stepType: Command
    name: Install Apache Web Server
    command: /genericArtifactDemo/install_dependencies.sh
    runAs: root
    timeoutInSeconds: 600
  - stepType: Command
    name: Stop Web Server
    command: /genericArtifactDemo/stop.sh
    runAs: root
    timeoutInSeconds: 60
  - stepType: Command
    name: Install New Version of Software
    command: /genericArtifactDemo/install.sh
    runAs: root
    timeoutInSeconds: 60
  - stepType: Command
    name: Start Web Server
    command: /genericArtifactDemo/start.sh
    runAs: root
    timeoutInSeconds: 60
  - stepType: Command
    name: stop and install
    command: |
      /scripts/stop.sh
      echo "Done stop.sh.."
      /scripts/install_dependencies.sh
      echo "Done install_dependencies.sh.."
      /scripts/install.sh
      echo "Done install.sh.."
    timeoutInSeconds: 1200
    runAs: root
    shell: /bin/sh
    onFailure:
       - stepType: Command
         command: /scripts/recovery_steps.sh
         name:"OnFailure step"
         timeoutInSeconds: 1200

Running the Deployment Configuration File

The DevOps service uses the RunCommand agent to run the commands specified in the configuration file on the target compute instance. For more information about enabling the RunCommand plugin, see the "Prerequisites" section in Deploying to an Instance Group. If the deployment configuration file contains placeholders, then they are replaced with the values defined in the parameter list of the deployment. See Configuring Parameters.