Creating a Custom Action in an Oracle Cloud Stack Template

Before You Begin

This 25-minute tutorial shows you how to add a custom action to a cloud resource in an existing Oracle Cloud Stack template.

Background

In Oracle Cloud Stack, custom actions enable template authors to run commands on a cloud resource's operating system, after the resource is provisioned. For example, you can use a custom action to create a database schema, deploy an application, or modify the default OS configuration. You can also use template functions to assign values to any required environment variables in your OS commands.

You cannot add custom actions to a template using the Oracle Cloud Stack console. You must edit the template file manually.

Custom actions are supported only for customer-managed cloud resources that provide a secure shell (SSH) interface. This tutorial executes a custom action on an Oracle Database Cloud Service instance.

What Do You Need?

Complete the tutorial Creating a Template for Oracle Cloud Stack
An SSH client, such as OpenSSH or PuTTY.

Export the Template

Sign in to Oracle Cloud.
From the Oracle Cloud Infrastructure Console, click the Navigation menu at the top left corner of the page, expand Platform Services, and then select Java.
Note: On some older Oracle Cloud accounts, you use the Oracle Cloud Infrastructure Classic Console. Click the Navigation menu , and then select Java.

Tip: You can access Cloud Stack from any Oracle Platform service.
From the Oracle Java Cloud Service console, click the Navigation menu at the top left corner of the page, and then select Cloud Stack.
From the Oracle Cloud Stack console, click Templates.

Description of the illustration click_templates.png
Click the Download icon to the right of the MyStackTemplate template. Save the template file to your local computer.
Open the file MyStackTemplate.yaml in a text editor.
Increment the value of templateVersion. For example, if the current is value is 1.0.0, change it to 1.0.1.
```
templateVersion: 1.0.1
```

Create a Software Component Resource

Tip: You can also download the finished MyStackTemplate.yaml.

Within resources, add a resource named dbactions and set its type to SoftwareComponent.
```
resources:
  dbactions:
    type: SoftwareComponent
  oracledb1: ...
```

Within this new resource, add the following configuration named createSchema.

resources:
  dbactions:
    type: SoftwareComponent
    parameters:
      configs:
        - actions: [CREATE]
          name: createSchema
          config: 
            'Fn::Base64':
              'Fn::Join':
                - "\n"
                -
                  - echo "Commands go here"
          runAsUser: oracle
          timeout: 1
          continueOnFailure: false

Be sure to use the exact spacing shown here. If you prefer, you can copy code-snippet-1.txt.

Add the following OS commands as a sequence of strings in the Fn::Join function.

'Fn::Join':
  - "\n"
  -
    - scriptFile=~/createSchema.sh
    - scriptLog=~/createSchema.log
    - rm -f ${scriptFile}
    - touch ${scriptFile}
    - touch ${scriptLog}
    - echo "sqlplus / as sysdba << EOF" >> ${scriptFile}
    - echo "drop user c##myappuser cascade;" >> ${scriptFile}
    - echo "create user c##myappuser identified by ${schemaPassword};" >> ${scriptFile}
    - echo "grant create session, create table, unlimited tablespace to c##myappuser;" >> ${scriptFile}
    - echo "quit" >> ${scriptFile}
    - echo "EOF" >> ${scriptFile}
    - sh ${scriptFile} >> ${scriptLog}

These commands create and run a script file. The script creates a new user in the local database. If you prefer, you can copy code-snippet-2.txt.

Within the Software Component resource, below the configs node, add an input named schemaPassword.
```
dbactions:
  type: SoftwareComponent
  parameters:
    configs:
      ...
    inputs:
      - name: schemaPassword
```
The ${schemaPassword} environment variable is used in the OS commands for this custom action.

Add the Software Component to the Database Resource

Locate the existing oracledb1 resource in the template file.

resources:
  dbactions:
    type: SoftwareComponent
    parameters:
      ...
  oracledb1:
    type: DBaaS
    parameters:
      ...

Below the parameters for oracledb1, add the following configuration named oracledb1-dbactions.
```
oracledb1:
  type: DBaaS
  parameters:
    ...
  configs:
    - name: oracledb1-dbactions
```

Use the Fn::GetResource function to get the dbactions resource.

oracledb1:
  type: DBaaS
  parameters:
    ...
  configs:
    - name: oracledb1-dbactions
      config:
        'Fn::GetResource': dbactions

Assign a value to the schemaPassword input. Use the Fn::GetParam function to get the value of the dbPassword template parameter.
```
oracledb1:
  type: DBaaS
  parameters:
    ...
  configs:
    - name: oracledb1-dbactions
      config:
        'Fn::GetResource': dbactions
      params:
        schemaPassword:
          'Fn::GetParam': dbPassword
```
If you prefer, you can copy code-snippet-3.txt. Or you can download the finished MyStackTemplate.yaml.
Save your changes.

Import the Template

Return to the Oracle Cloud Stack console.
Click Templates.
Click Import.
Use your browser to select MyStackTemplate.yaml on your local computer. Then click Import.

Test the Template

To the right of MyStackTemplate, click Create a stack with this template .
Configure the stack's parameters:
- Name: MyCustomActionStack
- Template: MyStackTemplate
- On Failure Retain Resources: Yes
- Database Password: Enter a password
- Confirm Database Password: Enter a password
The password must be 8 to 30 characters in length, and must contain at least one lowercase letter, one uppercase letter, one number, and one of these symbols: _, #, $. The password must begin with a letter.
To the right of SSH Public Key, click Edit.
Select the option Create a New Key, and then click Enter.
Click Download, and then click Done.
Click Next.
Click Confirm.
Refresh the Stacks page periodically until the stack is created.

Verify the Custom Action

From the Stacks page, click MyCustomActionStack.
Under Resources, locate oracledb1-dbactions.

Description of the illustration stack_resources_action.png
To the right of oracledb1-dbactions, click the Success link. Use the log to verify that the custom action was executed.
```
User script is executed successfully.
```
Click MyCustomActionStackDB to view the Oracle Database Cloud Service instance.
Within the Resources section, identify the Public IP address.
Extract the contents of the archive file sshkeybundle.zip that you downloaded when you created the stack.
Use an SSH client to connect to the public IP address as the opc user. Provide the location of the extracted private key file. For example:
```
ssh -i privateKey opc@IP_address
```
After connecting to the node, switch to the oracle user.
```
sudo su oracle
```

View the contents of the custom action's log file.

$ cat ~/createSchema.log

...
SQL>
User created.

SQL>
Grant succeeded.
...

Connect to the local database as myappuser. Enter the same password that you specified when you created the stack.
```
sqlplus c##myappuser/Your_DB_password
```
Note: If you make additional changes to your template, you will also need to change the templateVersion prior to importing it again.