4 Preparing the Appliance Configuration File

The appliance configuration file specifies the parameters of the appliance and the Oracle Cloud Infrastructure Compute Classic instance that hosts the appliance.

Before You Begin

  • Make sure that you’ve generated the necessary SSH key pairs, added the public keys to Oracle Cloud Infrastructure Compute Classic, and configured the required network settings in Oracle Cloud Infrastructure Compute Classic. See Preparing the OCI Compute Classic Environment.

  • Identify the shape that you’d like to use for the appliance instance. Select oc2m or a larger shape.

    The shape of an instance determines the number of CPU cores and the amount of memory that’s available for the instance. For information about the available shapes, see About Machine Images and Shapes in Using Oracle Cloud Infrastructure Compute Classic.

  • Decide the number and size of the data disks (storage volumes) that you want to attach to the appliance instance.

    You can attach up to nine data disks, each up to 2 TB in size.

  • Keep the following information ready:
    • The REST endpoint for your Oracle Cloud Infrastructure Compute Classic site. To find out the REST endpoint URL for your account, see REST API for Oracle Cloud Infrastructure Compute Classic.

    • The identity domain name, user name, and password for your Oracle Cloud Infrastructure Compute Classic site.

      Note:

      The user must have the Compute_Operations role. If this role isn’t assigned to the user or you’re not sure, then ask your Oracle Cloud Infrastructure Compute Classic administrator to ensure that the role is assigned to the user in Oracle Cloud My Services. See Managing User Roles in Managing and Monitoring Oracle Cloud.

      The account-creation email from Oracle would contain the identity domain name and user name as shown in the following example:


      Screenshot of a sample account-creation email.

      If you don’t have this information, contact your service administrator.

Steps

To prepare the appliance configuration file:

  1. Make sure that you have the latest version of the configuration file template.

    See Obtaining the Storage Software Appliance Image.

  2. Open the configuration file template in a text editor, and specify the required parameters. See Appliance Configuration Parameters.

  3. Validate the YAML format of the configuration file by using a tool such as YAML Lint (http://www.yamllint.com).

    Note:

    Oracle does not support or sponsor any third-party YAML validation tool.

Appliance Configuration Parameters

The appliance provisioning tool takes a configuration file, in YAML format, as an argument. In the configuration file, you must specify the parameters of the Oracle Cloud Infrastructure Compute Classic instance and Oracle Cloud Infrastructure Storage Software Appliance.

Configuration File Template

oracle-compute:
  endpoint: compute_endpoint
  user:
    name: compute_user_name
  orchestration:
    name: orchestration_name
  vm:
    name: compute_instance_name
    hostname: instance_hostname
    shape: shape
    image: image
    sshkeys: list_of_keys
    storage:
      - datadisk:
          name: storage_volume_name
          size: size
          property: property
      - datadisk:
          name: storage_volume_name
          size: size
          property: property
      - ...<up to nine data disks>
    networking:
      name: ip_reservation_name
      model: NIC_mode
      securitylists: list_of_securitylists
      ippool: ip_pool_name

Configuration Parameters

The following table lists the parameters in the appliance configuration template.

Note:

In the Parameter column of the table, the parameters are indented to indicate their hierarchy in the YAML format.
Parameter Description

oracle-compute

The parent parameter for the endpoint and user parameters.

   endpoint

The REST endpoint URL for your Oracle Cloud Infrastructure Compute Classic site.

Example:

endpoint: https://api-z13.compute.us2.oraclecloud.com

To find out the REST endpoint URL for your account:
  1. Sign in to the Oracle Cloud My Services application. See Signing In to the My Services Application in Managing and Monitoring Oracle Cloud.

    The My Services Dashboard is displayed. It lists the services that are assigned to your account.

  2. Look for Oracle Cloud Infrastructure Compute Classic.

  3. From the Actions You can select the action you would like to perform from the Actions menu. menu, select View Details. The Service Details page is displayed.

  4. Note the URL displayed in the REST Endpoint field under Additional Information.

   user

The parent parameter for the name parameter.

      name

The two-part Oracle Cloud Infrastructure Compute Classic user name, in the following format:

/Compute-identity_domain/user_name

The account-creation email from Oracle would contain the identity domain name and user name.

Note: The user must have the Compute_Operations role. If this role isn’t assigned to the user or you’re not sure, then ask your Oracle Cloud Infrastructure Compute Classic administrator to ensure that the role is assigned to the user in Oracle Cloud My Services. See Managing User Roles in Managing and Monitoring Oracle Cloud.

Example:

name: /Compute-acme/jack.jones@example.com

   orchestration

The parent parameter for the name parameter.

      name

The three-part name of the Oracle Cloud Infrastructure Compute Classic orchestration, in the following format:

/Compute-identity_domain/user_name/name

Example:

name: /Compute-acme/jack.jones@example.com/myOrch

Tip: Note down the name that you specify for the orchestration. If you happen to lose the configuration file, you’ll need this name to retrieve the configuration parameters and use them to reconstruct the configuration file.

   vm

Parent parameter for all the parameters of the Oracle Cloud Infrastructure Compute Classic instance.

      name

The three-part name of the instance, in the following format:

/Compute-identity_domain/user_name/name

Example:

name: /Compute-acme/jack.jones@example.com/myInstance

Note that, internally, Oracle Cloud Infrastructure Compute Classic generates an ID for the instance. The full name of an Oracle Cloud Infrastructure Compute Classic instance is the three-part name that you specify followed by the instance ID, as shown in the following example:

/Compute-acme/jack.jones@example.com/myInstance/300a7479-ec90-4826-98b9-a725662628f1

      hostname

The host name prefix for the instance. The name must not contain periods. The name you specify here is prefixed to the domain name (example: compute-acme.oraclecloud.com) to derive the full host name of the instance.

Example:

hostname: myAppliance

      shape

The name of the shape, which defines the number of CPUs and the RAM that will be allocated to the instance.

Example:

shape: oc2m

For information about the available shapes, see About Machine Images and Shapes in Using Oracle Cloud Infrastructure Compute Classic.

      image

The three-part name of the machine image that must be used to create the Oracle Cloud Infrastructure Compute Classic instance, in the following format:

/Compute-identity_domain/user/image_name

Here image_name is the name that you noted earlier while registering the image.

Example:

image: /Compute-acme/jack.jones@example.com/OSCSA-CD-image-v1.3

To get a list of the available machine images, send the GET /imagelist/Compute-identity_domain/user HTTP request to your Oracle Cloud Infrastructure Compute Classic site. See REST API for Oracle Cloud Infrastructure Compute Classic.

      sshkeys

A comma-separated list of the SSH public keys that you want to associate with the instance.

For each key, specify the three-part name in the /Compute-identity_domain/user/key format.

You should have previously generated these keys and added them to Oracle Cloud Infrastructure Compute Classic. See Preparing the OCI Compute Classic Environment.

Example:

sshkeys: ["/Compute-acme/jack.jones@example.com/ssh_key1","/Compute-acme/jane.williams@example.com/ssh_key2"]

      storage

The parent parameter for one or more datadisk parameters.

         datadisk

Each datadisk parameter specifies the details of one disk, which is a storage volume in Oracle Cloud Infrastructure Compute Classic. The data disks are attached to the appliance instance. They provide local cache capacity for the appliance. See Best Practices – Configuring Cache Storage and Best Practices – Determining the Cache Size.

All the data disks that are attached to the appliance instance are combined into a resizeable logical volume group, named oracle_data_vg, which is mounted on the appliance instance at /opt/oracle/datadisk.

Note: At any time, you can add more data disks. See Adding Data Disks to the Appliance Instance.

You can attach up to nine data disks, each up to 2 TB in size.

            name

The three-part name of the storage volume, in the following format:

/Compute-identity_domain/user_name/volume_name

Note: Don’t specify the name of a storage volume that already exists in Oracle Cloud Infrastructure Compute Classic.

Example:

name: /Compute-acme/jack.jones@example.com/myVolume1

            size

The size of the storage volume.

Use one of the following abbreviations for the unit of measurement:
  • B or b for bytes

  • K or k for kilobytes

  • M or m for megabytes

  • G or g for gigabytes

  • T or t for terabytes

The allowed range is from 1 GB to 2 TB, in increments of 1 GB.

Example:

size: 10G

            property
The three-part name of the storage property to be used for creating the storage volume.
  • For storage volumes that require low latency and fast I/O, such as for storing database files, specify /oracle/public/storage/latency.

  • For all other storage volumes, select /oracle/public/storage/default.

Example:

property: /oracle/public/storage/default

      networking

The parent parameter for the networking parameters for the Oracle Cloud Infrastructure Compute Classic instance.

         name

The three-part name of the reservation that should be created in Oracle Cloud Infrastructure Compute Classic for the public IP address of the instance, in the following format:

/Compute-identity_domain/user_name/ip_reservation_name

Example:

name: /Compute-acme/jack.jones@example.com/myIPres

         model

The type of network interface card (NIC).

Specify e1000 as the value.

         securitylists

A comma-separated list of the security lists that you want to add the instance to.

You must have already identified (or created) these security lists. See Preparing the OCI Compute Classic Environment.

Example:

securitylist: ["/Compute-acme/jack.jones@example.com/mySeclist1","/Compute-acme/jack.jones@example.com/mySeclist2"]

         ippool

The pool of public IP addresses from which an address must be reserved for the Oracle Cloud Infrastructure Compute Classic instance.

Specify /oracle/public/ippool as the value.

Sample Configuration File

oracle-compute:
  endpoint: https://api-z13.compute.us2.oraclecloud.com
  user:
    name: /Compute-acme/jack.jones@example.com
  orchestration:
    name: /Compute-acme/jack.jones@example.com/myOrch
  vm:
    name: /Compute-acme/jack.jones@example.com/myInstance
    hostname: myAppliance
    shape: oc2m
    image: /Compute-acme/jack.jones@example.com/OSCSA-CD-image-v1.3
    sshkeys: ["/Compute-acme/jack.jones@example.com/ssh_key","/Compute-acme/jane.williams@example.com/ssh_key"]
    storage:
      - datadisk:
          name: /Compute-acme/jack.jones@example.com/myVolume1
          size: 10G
          property: /oracle/public/storage/default
      - datadisk:
          name: /Compute-acme/jack.jones@example.com/myVolume2
          size: 10G
          property: /oracle/public/storage/default
    networking:
      name: /Compute-acme/jack.jones@example.com/myIPres
      model: e1000
      securitylist: ["/Compute-acme/jack.jones@example.com/mySeclist1","/Compute-acme/jack.jones@example.com/mySeclist2"]
      ippool: /oracle/public/ippool