Create a new Oracle Cloud API Gateway machine¶

Creating an Oracle Cloud API Gateway machine lets Certificate Manager - SaaS discover and provision the TLS certificates that the API gateways in one Oracle Cloud Infrastructure (OCI) compartment serve on their custom domains. Certificate Manager - SaaS connects to the OCI API Gateway API directly and signs each request with an OCI API signing key, so you don't need a VSatellite. After you create the machine, you can provision certificates to it.

Prepare Oracle Cloud¶

Use a dedicated user and group for Certificate Manager - SaaS, and grant them access only to the compartment the machine manages.

1. In the Oracle Cloud Console, go to Identity & Security > Users, and create a user only for Certificate Manager - SaaS. Don't reuse a person's account or an administrator account.

2. Generate an RSA key pair in PEM format, for example:

   openssl genrsa -out oci_api_key.pem 2048
   openssl rsa -in oci_api_key.pem -pubout -out oci_api_key_public.pem
   

   Keys created with ssh-keygen (OpenSSH format) aren't supported. If you encrypt the private key with a passphrase, you enter the passphrase when you create the machine.

3. On the user's page, go to API Keys > Add API Key, and upload the public key. Copy the fingerprint that the Console shows.

4. Create a group that contains only this user.

5. Create a policy for the compartment the machine manages. Replace <group> and <compartment> with your own values.

   • For discovery and provisioning:

     Allow group <group> to manage api-gateways in compartment <compartment>
     Allow group <group> to manage api-certificates in compartment <compartment>
     Allow group <group> to read api-workrequests in compartment <compartment>
     

   • For discovery only:

     Allow group <group> to read api-gateways in compartment <compartment>
     Allow group <group> to read api-certificates in compartment <compartment>
     

   Note

   • manage api-gateways is the only permission that allows Certificate Manager - SaaS to switch an API gateway's certificate. It also allows the user to delete API gateways and move them to another compartment. Together with manage api-certificates, it also allows the user to create API gateways. Keep the group limited to this one user.
   • read api-workrequests is required separately. The manage permissions don't include it, and Certificate Manager - SaaS follows every change it makes through an OCI work request.
   • A policy on a compartment also covers its child compartments. Certificate Manager - SaaS never changes API gateways or certificates outside the machine's compartment, but for a credential limited to a single compartment, choose a compartment without child compartments. For the root compartment, write in tenancy instead of in compartment <compartment>.
   • No permission on the OCI Certificates service is required.

Create the machine¶

1. In Tenancy OCID, enter the OCID of your tenancy. It starts with ocid1.tenancy. and is shown under Tenancy Information in the Oracle Cloud Console.

2. In User OCID, enter the OCID of the user that owns the API signing key. It starts with ocid1.user..

3. In API Key Fingerprint, enter the fingerprint of the API signing key's public key, as shown under the user's API keys in the Oracle Cloud Console.

4. In API Signing Private Key, paste the whole RSA private key in PEM format, from its BEGIN line to its END line.

   Warning

   Remember to store your username and password securely when creating a new machine. For security reasons, you will not be able to modify the fields under the "Access" tab without these credentials. This ensures that only authorized individuals can modify these fields.

5. (Optional) In API Signing Key Passphrase, enter the passphrase of the private key. Leave it empty for an unencrypted key.

6. In Region, enter the region identifier, for example us-ashburn-1. Use the full identifier, not its short code (such as iad). The field accepts only lowercase letters, digits, and hyphens.

   Note

   Dedicated regions that aren't in the OCI SDK's region list aren't supported.

7. In Compartment OCID, enter the OCID of the compartment to manage. For the root compartment, enter the tenancy OCID.

8. Click Test Access, then click Continue. Continue is enabled only after the test succeeds.

   Note

   The test checks the credentials, the region, and access to the compartment's API gateways. It passes for a compartment that has no API gateways, and it doesn't check the certificate or work request permissions. A missing permission shows up during the first discovery or provisioning.

What's next?¶

Refer back to Create a new machine to finish setting up your new machine by configuring Discovery and Provisioning scheduling. When you configure discovery, you can turn on Exclude Expired Certificates to skip certificates that have already expired.

Discovery reports each API Gateway certificate in the compartment once, with one installation for each API gateway that serves it. A certificate that no active or updating API gateway uses gets one installation, with the API Gateway OCID (unbound). A certificate from another compartment is also reported when an API gateway in the machine's compartment serves it.

For existing machines:

• Now that you have one or more machines created, you can provision certificates to those machines.
• You can also discover certificates on machines to enable easy tracking of certificates deployed to your machines.