|
| 1 | +### How to use variables with managed `build stage` (OCI Build pipeline) or using `shell stage` (OCI Deployment pipeline) |
| 2 | + |
| 3 | +------ |
| 4 | +The procedure demonstrates some of the sample usage of variables within the build or shell stage. The format and usage of variables for the shell stage or managed build stage are similar. |
| 5 | + |
| 6 | +* Specific instruction to clone only this example. |
| 7 | + |
| 8 | + ``` |
| 9 | + $ git init oci-devops-variables-shell-buildpiepline |
| 10 | + $ cd oci-project-cascadedelete |
| 11 | + $ git remote add origin <url to this git repo> |
| 12 | + $ git config core. sparse checkout true |
| 13 | + $ echo "oci-config-examples/oci-devops-variables-shell-buildpiepline/*">>.git/info/sparse-checkout |
| 14 | + $ git pull --depth=1 origin main |
| 15 | +
|
| 16 | + ``` |
| 17 | + |
| 18 | +<details> |
| 19 | +<summary> Basic Configuration - shell stage - Click to View details. </summary> |
| 20 | + |
| 21 | +```yaml |
| 22 | +version: 0.1 |
| 23 | +component: command |
| 24 | +timeoutInSeconds: 10000 |
| 25 | +shell: bash |
| 26 | +failImmediatelyOnError: true |
| 27 | + |
| 28 | +inputArtifacts: |
| 29 | + - name: sample-kube-yaml |
| 30 | + type: URL |
| 31 | + url: https://raw.githubusercontent.com/kubernetes/website/main/content/en/examples/application/deployment.yaml |
| 32 | + location: ${OCI_WORKSPACE_DIR}/ngnix.yaml |
| 33 | + |
| 34 | +steps: |
| 35 | + - type: Command |
| 36 | + timeoutInSeconds: 600 |
| 37 | + name: "stepOne" |
| 38 | + command: | |
| 39 | + echo "Step One.." |
| 40 | + ls -ltr |
| 41 | +
|
| 42 | + onFailure: |
| 43 | + - type: Command |
| 44 | + command: | |
| 45 | + echo "Handled Failure for Step One" |
| 46 | + timeoutInSeconds: 40 |
| 47 | + |
| 48 | + - type: Command |
| 49 | + timeoutInSeconds: 600 |
| 50 | + name: "stepTwo" |
| 51 | + command: | |
| 52 | + echo "Step two" |
| 53 | + ls -ltr |
| 54 | +
|
| 55 | + onFailure: |
| 56 | + - type: Command |
| 57 | + command: | |
| 58 | + echo "Handled Failure for Step One" |
| 59 | + timeoutInSeconds: 40 |
| 60 | +``` |
| 61 | +- Details of the steps. |
| 62 | + - The above is a basic shell stage usage. |
| 63 | + - Here we are using a URL to download a config file using the option `inputArtifacts`. |
| 64 | + - the files that are downloaded using `inputArtifacts` will be available throughout the stage for all the steps. |
| 65 | +- Execution result. |
| 66 | +  |
| 67 | +</details> |
| 68 | +<details> |
| 69 | +<summary> Use of env/variables - Click to View details.</summary> |
| 70 | + |
| 71 | +```yaml |
| 72 | +version: 0.1 |
| 73 | +component: command |
| 74 | +timeoutInSeconds: 10000 |
| 75 | +shell: bash |
| 76 | +failImmediatelyOnError: true |
| 77 | +env: |
| 78 | + variables: |
| 79 | + NAMESPACE: "initialNameSpace" |
| 80 | +inputArtifacts: |
| 81 | + - name: sample-kube-yaml |
| 82 | + type: URL |
| 83 | + url: https://raw.githubusercontent.com/kubernetes/website/main/content/en/examples/application/deployment.yaml |
| 84 | + location: ${OCI_WORKSPACE_DIR}/ngnix.yaml |
| 85 | +
|
| 86 | +steps: |
| 87 | + - type: Command |
| 88 | + timeoutInSeconds: 600 |
| 89 | + name: "stepOne" |
| 90 | + command: | |
| 91 | + echo "Step One.." |
| 92 | + ls -ltr |
| 93 | + echo ${NAMESPACE} |
| 94 | + NAMESPACE="nameSpaceFromStepOne" |
| 95 | +### The value of an env variable is changed here and the updated value will be available for further steps. |
| 96 | +
|
| 97 | + onFailure: |
| 98 | + - type: Command |
| 99 | + command: | |
| 100 | + echo "Handled Failure for Step One" |
| 101 | + timeoutInSeconds: 40 |
| 102 | +
|
| 103 | + - type: Command |
| 104 | + timeoutInSeconds: 600 |
| 105 | + name: "stepTwo" |
| 106 | + command: | |
| 107 | + echo "Step two" |
| 108 | + ls -ltr |
| 109 | + echo ${NAMESPACE} |
| 110 | +
|
| 111 | + onFailure: |
| 112 | + - type: Command |
| 113 | + command: | |
| 114 | + echo "Handled Failure for Step One" |
| 115 | + timeoutInSeconds: 40 |
| 116 | +``` |
| 117 | +- Details of steps. |
| 118 | + - This follows a key-value pair. |
| 119 | + - The key must follow POSIX environment variable compliant. |
| 120 | + - The value can be any string. |
| 121 | + - The scope of this variable is the execution of the build specification file. This means the value is available only within the stage across the steps. |
| 122 | + - If the value of the variable contains a new line(\n) or carriage return(\r) character, then they are replaced with space in the subsequent steps. |
| 123 | + - The change of value with a step is available for further steps as well. |
| 124 | +- Execution result. |
| 125 | +  |
| 126 | +</details> |
| 127 | + |
| 128 | +<details> |
| 129 | +<summary>Use of env/vaultVariables - Click to View details.</summary> |
| 130 | + |
| 131 | +```yaml |
| 132 | +version: 0.1 |
| 133 | +component: command |
| 134 | +timeoutInSeconds: 10000 |
| 135 | +shell: bash |
| 136 | +failImmediatelyOnError: true |
| 137 | +env: |
| 138 | + variables: |
| 139 | + NAMESPACE: "initialNameSpace" |
| 140 | + vaultVariables: |
| 141 | + MYSECRET: "OCID of Vault Secret" |
| 142 | +inputArtifacts: |
| 143 | + - name: sample-kube-yaml |
| 144 | + type: URL |
| 145 | + url: https://raw.githubusercontent.com/kubernetes/website/main/content/en/examples/application/deployment.yaml |
| 146 | + location: ${OCI_WORKSPACE_DIR}/ngnix.yaml |
| 147 | +
|
| 148 | +steps: |
| 149 | + - type: Command |
| 150 | + timeoutInSeconds: 600 |
| 151 | + name: "stepOne" |
| 152 | + command: | |
| 153 | + echo "Step One.." |
| 154 | + ls -ltr |
| 155 | + echo ${NAMESPACE} |
| 156 | + NAMESPACE="nameSpaceFromStepOne" |
| 157 | + echo "Its a dummy view - $MYSECRET" a |
| 158 | +
|
| 159 | + onFailure: |
| 160 | + - type: Command |
| 161 | + command: | |
| 162 | + echo "Handled Failure for Step One" |
| 163 | + timeoutInSeconds: 40 |
| 164 | +
|
| 165 | + - type: Command |
| 166 | + timeoutInSeconds: 600 |
| 167 | + name: "stepTwo" |
| 168 | + command: | |
| 169 | + echo "Step two" |
| 170 | + ls -ltr |
| 171 | + echo ${NAMESPACE} |
| 172 | +
|
| 173 | + onFailure: |
| 174 | + - type: Command |
| 175 | + command: | |
| 176 | + echo "Handled Failure for Step One" |
| 177 | + timeoutInSeconds: 40 |
| 178 | +``` |
| 179 | + |
| 180 | +- Details of steps. |
| 181 | + - `vaultVariables` are used to read secrets from the build or shell stage with a pipeline. |
| 182 | + - The key must be a string and POSIX environment variable compliant. |
| 183 | + - The value must be an OCID of the secret from the vault. |
| 184 | + - The vault and build pipeline must be of the same tenancy. |
| 185 | + - The tenancy must have an appropriate policy to allow build pipeline resources to access the secret. |
| 186 | + - The scope of this value is available across the stage, for all the steps. |
| 187 | +- Execution result. |
| 188 | +  |
| 189 | +</details> |
| 190 | + |
| 191 | +<details> |
| 192 | +<summary>Use of env/exportedVariables - Click to View details.</summary> |
| 193 | + |
| 194 | +```yaml |
| 195 | +version: 0.1 |
| 196 | +component: command |
| 197 | +timeoutInSeconds: 10000 |
| 198 | +shell: bash |
| 199 | +failImmediatelyOnError: true |
| 200 | +env: |
| 201 | + variables: |
| 202 | + NAMESPACE: "initialNameSpace" |
| 203 | + vaultVariables: |
| 204 | + MYSECRET: "OCI of the Vault Secret" |
| 205 | + exportedVariables: |
| 206 | + - exportVariableFromStepOne |
| 207 | +inputArtifacts: |
| 208 | + - name: sample-kube-yaml |
| 209 | + type: URL |
| 210 | + url: https://raw.githubusercontent.com/kubernetes/website/main/content/en/examples/application/deployment.yaml |
| 211 | + location: ${OCI_WORKSPACE_DIR}/ngnix.yaml |
| 212 | +
|
| 213 | +steps: |
| 214 | + - type: Command |
| 215 | + timeoutInSeconds: 600 |
| 216 | + name: "stepOne" |
| 217 | + command: | |
| 218 | + echo "Step One.." |
| 219 | + ls -ltr |
| 220 | + echo ${NAMESPACE} |
| 221 | + NAMESPACE="nameSpaceFromStepOne" |
| 222 | + echo "Its a dummy view - $MYSECRET" |
| 223 | + export exportVariableFromStepOne="Value_from_StepOne" |
| 224 | +
|
| 225 | + onFailure: |
| 226 | + - type: Command |
| 227 | + command: | |
| 228 | + echo "Handled Failure for Step One" |
| 229 | + timeoutInSeconds: 40 |
| 230 | +
|
| 231 | + - type: Command |
| 232 | + timeoutInSeconds: 600 |
| 233 | + name: "stepTwo" |
| 234 | + command: | |
| 235 | + echo "Step two" |
| 236 | + ls -ltr |
| 237 | + echo ${NAMESPACE} |
| 238 | + echo "${exportVariableFromStepOne}" |
| 239 | +
|
| 240 | + onFailure: |
| 241 | + - type: Command |
| 242 | + command: | |
| 243 | + echo "Handled Failure for Step One" |
| 244 | + timeoutInSeconds: 40 |
| 245 | +``` |
| 246 | +- Details of steps. |
| 247 | + - `exportedVariables` can be used to expose values from a stage to subsequent stages. |
| 248 | + - The name of the variable must be a string and POSIX environment variable compliant. |
| 249 | + - The value can be assigned in any of the steps inside the build specification file. |
| 250 | + - The scope of this variable is the build pipeline. |
| 251 | + |
| 252 | +- Execution result. |
| 253 | +  |
| 254 | +</details> |
| 255 | + |
| 256 | +<details> |
| 257 | +<summary>Parsing a variable value between steps - Click to View details.</summary> |
| 258 | + |
| 259 | +```yaml |
| 260 | +version: 0.1 |
| 261 | +component: command |
| 262 | +timeoutInSeconds: 10000 |
| 263 | +shell: bash |
| 264 | +failImmediatelyOnError: true |
| 265 | +env: |
| 266 | + variables: |
| 267 | + NAMESPACE: "initialNameSpace" |
| 268 | + vaultVariables: |
| 269 | + MYSECRET: "OCID of Vault Secret" |
| 270 | + exportedVariables: |
| 271 | + - exportVariableFromStepOne |
| 272 | + - localValueFromStepTwo |
| 273 | +inputArtifacts: |
| 274 | + - name: sample-kube-yaml |
| 275 | + type: URL |
| 276 | + url: https://raw.githubusercontent.com/kubernetes/website/main/content/en/examples/application/deployment.yaml |
| 277 | + location: ${OCI_WORKSPACE_DIR}/ngnix.yaml |
| 278 | +
|
| 279 | +steps: |
| 280 | + - type: Command |
| 281 | + timeoutInSeconds: 600 |
| 282 | + name: "stepOne" |
| 283 | + command: | |
| 284 | + echo "Executing Step One.." |
| 285 | + ls -ltr |
| 286 | + echo ${NAMESPACE} |
| 287 | + NAMESPACE="nameSpaceFromStepOne" |
| 288 | + echo "It a dummy view - $MYSECRET" |
| 289 | + export exportVariableFromStepOne="Value_from_StepOne" |
| 290 | + |
| 291 | +
|
| 292 | + onFailure: |
| 293 | + - type: Command |
| 294 | + command: | |
| 295 | + echo "Handled Failure for Step One" |
| 296 | + timeoutInSeconds: 40 |
| 297 | +
|
| 298 | + - type: Command |
| 299 | + timeoutInSeconds: 600 |
| 300 | + shell: bash |
| 301 | + name: "stepTwo" |
| 302 | + command: | |
| 303 | + echo "Executing Step Two" |
| 304 | + ls -ltr |
| 305 | + echo ${NAMESPACE} |
| 306 | + echo "${exportVariableFromStepOne}" |
| 307 | + export localValueFromStepTwo=${exportVariableFromStepOne} |
| 308 | + echo "Local value from step2 - ${localValueFromStepTwo}" |
| 309 | +
|
| 310 | + onFailure: |
| 311 | + - type: Command |
| 312 | + command: | |
| 313 | + echo "Handled Failure for Step Two" |
| 314 | + timeoutInSeconds: 40 |
| 315 | +
|
| 316 | + - type: Command |
| 317 | + timeoutInSeconds: 600 |
| 318 | + shell: /bin/sh |
| 319 | + name: "stepThree" |
| 320 | + command: | |
| 321 | + echo "Executing Step three" |
| 322 | + echo "Value from Step2 for Step3 - ${localValueFromStepTwo}" |
| 323 | +
|
| 324 | + onFailure: |
| 325 | + - type: Command |
| 326 | + command: | |
| 327 | + echo "Handled Failure for Step Three" |
| 328 | + timeoutInSeconds: 40 |
| 329 | +``` |
| 330 | + |
| 331 | +- Details of steps |
| 332 | + - In the above, we have created a local variable `localValFromStepTwo` with a value. |
| 333 | + - The same is exported so that the same can be used from further steps. |
| 334 | + - The export work across steps as well as different types of shell types. Here we are using `/bin/sh` and `bash`. |
| 335 | +- Execution result |
| 336 | +  |
| 337 | +</details> |
| 338 | +<details> |
| 339 | +<summary> Certain consideration - Click to View details.</summary> |
| 340 | + |
| 341 | +- The name of the variable must be a string and POSIX environment variable compliant. |
| 342 | +- Users won't be able to use the same key name for `vaultVariables` and `exportedVariables`. |
| 343 | +- Read [here](https://docs.oracle.com/en-us/iaas/Content/devops/using/reference.htm) for more details. |
| 344 | +</details> |
| 345 | + |
| 346 | +Read more |
| 347 | +--- |
| 348 | + |
| 349 | +- OCI DevOps service - https://docs.oracle.com/en-us/iaas/Content/devops/using/home.htm |
| 350 | + |
| 351 | +Contributors |
| 352 | +=========== |
| 353 | + |
| 354 | +- Author: [Rahul M R](https://github.com/RahulMR42). |
| 355 | +- Collaborators: |
| 356 | +- Last release: November 2023 |
| 357 | + |
| 358 | +### Back to examples. |
| 359 | +---- |
| 360 | + |
| 361 | +- 🏝️ [Back to OCI Devops sample](./../../README.md) |
| 362 | + |
0 commit comments