You can get started in Oracle Cloud Infrastructure (OCI) with very little effort, but managing non-trivial compute environments often requires automating some steps. OCI includes a “Marketplace” where Oracle and others offer software that can be used by end-users. Some of this software incurs an expense, other software does not. Similarly, some of this software requires accepting a license agreement, or some “Terms of Use.” This blog entry provides an overview of the OCI concepts related to these “agreements.” Understanding these concepts is important when automating certain types of operations within OCI, such as creating compute instances from OCI Marketplace images.

Some compute images include these agreements and you must agree to them before OCI will create the compute instance. Using a web browser, this is very easy: the OCI Cloud Console offers a check box to check. For Oracle Solaris, the prompt for this check box is “I have reviewed and accept the Terms of Use for Oracle Solaris on the Oracle Cloud Infrastructure Marketplace.” If you are automating the creation of an instance, you must also automate the acceptance of these agreements. We will introduce the concepts you must understand to automate these agreements in this blog entry, and the steps you take to use those concepts. This entry describes these in general, without referring to the specific actions needed in any particular automation environment, e.g. the OCI CLI, the OCI Python API, using the Terraform provider, etc. We will illustrate the use of those concepts in future blog entries, using those specific technologies and more.                           

We will first define some terms:

  • instance: an OCI virtual machine
  • image: a bootable representation of a specific version of an operating system, to be booted as an instance
  • listing: an item in the OCI marketplace catalog that represents a product or image that can be used on OCI; it contains one or more packages
  • package: an object in the marketplace; for Oracle Solaris this is an image that can be launched on OCI; a listing may have multiple versions, and each is represented by a package; each package may have one or more agreements
  • package agreement: an agreement associated with a package, shown in the Cloud Console as a checkbox; the user must accept this before using the image or package
  • signature: an ASCII string that is generated by OCI on demand, and that can be used to confirm with OCI that you are agreeing to the terms of the agreement
  • accepted agreement: this is the package’s agreement along with the digital signature.

The goal of the automation steps is an “Accepted Agreement” that has been submitted to OCI with a valid signature.

Some of the actions you can take include:

  • get a list of the listings that match certain criteria, including partial name search, product category, etc.
  • get one listing and its associated packages
  • select a package version
  • get the optional list of agreements for that package
  • retrieve an agreement to be accepted
  • accept that agreement

Submitting an accepted agreement along with a signature requires first getting some objects from OCI:

  • the list of agreements associated with this package
  • a signature for each agreement in the list
  • the ID of the listing that you want to use
  • the desired version of the package for that listing
  • the OCI compartment ID in which you will use that package

You can query OCI for the list of agreements needed to use a package. Issuing that query requires:

  • the OCI ID of the listing, which leads to the OCI ID of the package
  • the desired version of the package

 

With those requirements in mind, the steps needed to accept an agreement are:

  1. Look up the desired listing(s) using the name of the listing.
  2. If necessary, look through the list of listings to find the one that you want.
  3. Use the listing ID and version number to retrieve the ID of the specific package.
  4. Use the listing ID and the package version to get the list of agreements, if any.
  5. Get each agreement, which comes with a digital signature created by OCI just before sending the agreement to your code.
  6. Submit the agreement and signature.

 

Once you have submitted to the agreement, OCI remembers this for future uses of the same package by your OCI user account. This also means that you can manually agree to the agreement, once, using the Oracle Cloud Console, and then programmatically use that package without writing code to automate agreement-signing. But what fun would that be?