Creating Custom Actions

This topic does not apply to Oracle Cloud at Customer.

Use Software Components in your Oracle Cloud Stack template to execute custom operating system (OS) commands or scripts after a stack resource is provisioned.

For example, you can use custom actions to automatically install an OS package, create a database schema, or deploy an application.

For an introduction, see What are Custom Actions.

Topics

• Creating a Software Component

• Adding a Software Component to a Resource

• Adding a Condition to a Software Component

• Custom Action Best Practices

Creating a Software Component

Define custom actions in your Oracle Cloud Stack template within a special type of resource called a software component.

1. Access the Oracle Cloud Stack console, and then edit your template.
2. To the right of Software components, click Add software component .
3. Enter a name for the software component.
4. Enter a name for the first configuration in this software component.
5. Set the actions to CREATE. All custom actions run after the target cloud resource is created.
6. For config, enter one or more Bash OS commands as a Base64 encoded string. Use the following YAML structure:

   Fn::Base64:
     Fn::Join:
       - "\n"
       -
         - bash_command
         - bash_command

   For example:

   'Fn::Base64':
     'Fn::Join':
       - "\n"
       -
         - touch ~/stack.out
         - echo 'Updating hosts' >> ~/stack.out
         - echo 'myhost 192.168.1.10' >> /etc/hosts

   Tip:

   Be sure that all members of the same sequence have the same indentation. The following example is invalid:

   'Fn::Base64':
     'Fn::Join':
       - "\n"
       -
       - This is 
       - not valid

7. For runAsUser, select an OS user. Oracle Cloud Stack will run the commands in this configuration as the selected user.
8. Enter a timeout in minutes. If this configuration does not complete after the specified time period, it will fail.
9. Set ContinueOnFailure to true if stack creation should continue if this configuration fails or times out (a warning is added to the activity log).
10. For each additional configuration that you want to create in the software component, click Add another software component configuration , and then repeat from step 4.
11. If the OS commands in any of your configurations utilize environment variables, then define an input for each environment variable:
    1. Click Add another software component input .
    2. For name, enter the name of the environment variable.
       For example, if a configuration includes ${dbPassword}, then enter dbPassword.
12. Click Apply changes.
13. Repeat from step 2 for each additional software component that you want to create.
14. Click Save the current template .

Adding a Software Component to a Resource

Configure a template resource so that Oracle Cloud Stack executes custom actions after provisioning the resource.

1. Access the Oracle Cloud Stack console, and then edit your template.
2. From the canvas area, right-click a resource and select Edit.
3. To the right of Software component, click Add software component .
4. Select the name of an existing software component.
5. If the selected software component defines one or more inputs, enter values for these input fields.
   You can enter static text, or use template functions like GetParam.
6. Click Apply changes.
7. Click Save the current template .

Adding a Condition to a Software Component

Assign a global condition to a software component in your Oracle Cloud Stack template.

If the condition evaluates to false during the creation of a stack, the custom actions in this software component will not be executed. See Defining Global Conditions.

1. Access the Oracle Cloud Stack console, and then edit your template.
2. To the left of Software components, click .
3. To the right of the software component that you want to modify, click Edit .
4. From the Conditions field, select an existing condition.
5. Click Apply Changes.
6. Click Save the current template .

Custom Action Best Practices

Consider these best practices when creating Software Components in an Oracle Cloud Stack template.

• The use of template functions, such as GetParam, is not supported within the OS commands of a custom action.

• Program a custom action so that it can run multiple times without failing or behaving unexpectedly (idempotent). A custom action might be run more than once in the following scenarios:

  • Oracle Cloud Stack retries the execution of a custom action after a communication failure with the target resource.

  • If you create a cloud stack with the RETAIN option, and then resume the stack after a resource provisioning failure, Oracle Cloud Stack also (re)executes any custom actions that are associated with the failed resource.

• In a custom action, return 0 to indicate success and return 1 to indicate a failure.

• By default, all existing resources are terminated if there is a failure during the creation of a stack, which includes the deletion of any log files generated by a custom action. To facilitate troubleshooting, record log messages to an external location like cloud storage.

• You can use wget, curl, or similar OS commands to download scripts and other files to the administration node in the target cloud resource. For example, you could download and extract an archive file found in an Oracle Cloud Infrastructure Object Storage container, and then execute one or more scripts found in the archive.