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: Built-in variables can also be used. To avoid conflict, built-in
variables are prefixed with Built-in variables are:
|
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, For example, if you assign the destination directory in the
deployment configuration file as
|
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 For example, if the general artifact specifies a single file,
|
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
|
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 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 For example, if you specify the command, |
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.