Skip to main content
Version: 18.x (unreleased)

Join Services with Oracle Cloud

This guide will explain how to use the Oracle join method to configure Teleport processes to join your Teleport cluster without sharing any secrets when they are running in an Oracle Cloud Infrastructure (OCI) Compute instance.

The Oracle join method is available to any Teleport process running on an OCI Compute instance.

Prerequisites​

  • A running Teleport cluster version 17.3.0 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl admin tool and tsh client tool.

    Visit Installation for instructions on downloading tctl and tsh.

  • An OCI Compute instance to host a Teleport service.
  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example: 
    tsh login --proxy=teleport.example.com --user=email@example.com
    tctl status
    Cluster  teleport.example.com
    Version  17.0.0-dev
    CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/5. Create the Oracle joining token​

Configure your Teleport Auth Service with a special dynamic token which will allow services from your OCI tenants to join your Teleport cluster.

Under the hood, services will prove that they are running in your OCI tenant by sending a presigned self-authentication request to the OCI API for the Auth Service to execute.

Create the following token.yaml file with an oracle.allow rule specifying the Oracle tenant(s), compartment(s), and region(s) in which your OCI Compute instances will run:

# token.yaml
kind: token
version: v2
metadata:
  # The token name is not a secret because instances must prove that they are
  # running in your Oracle tenant to use this token.
  name: oracle-token
spec:
  # Use the minimal set of roles required (e.g. Node, Proxy, App, Kube, DB, WindowsDesktop).
  roles: [Node]

  # Set the join method allowed for this token.
  join_method: oracle

  oracle:
    allow:
      # OCID of the tenancy to allow instances to join from. Required.
      - tenancy: "ocid1.tenancy.oc1..<unique ID>"
        # (Optional) OCIDs of compartments to allow instances to join from. Only the direct parent
        # compartment applies; i.e. nested compartments are not taken into account.
        # If empty, instances can join from any compartment in the tenancy.
        parent_compartments: ["ocid1.compartment.oc1...<unique_ID>"]
        # (Optional) Regions to allow instances to join from. Both full names ("us-phoenix-1")
        # and abbreviations ("phx") are allowed. If empty, instances can join from any region.
        regions: ["example-region"]

Run the following command to create the token:

tctl create token.yaml

Step 2/5. Configure permissions​

Every OCI Compute instance needs permission to authenticate itself with the Oracle Cloud API so the presigned request can succeed.

Create a dynamic group​

In the OCI console, navigate to Identity/Domains. Select your domain, then select Dynamic groups. Click Create dynamic group. Create a group with the following matching rule, using the OCID of the compartment your instance is in:

Any {instance.compartment.id = 'compartment-id'}

tip

To minimize unnecessary permissions, configure your matching rules to match the rules in the token created in step 1.

Add policy to group​

In the OCI console, navigate to Identity/Domains/Policy. Click Create Policy. Create the following policy, using the name of the selected identity domain:

Allow dynamic-group 'identity-domain'/'join-teleport' to inspect authentication in tenancy

Step 3/5. Install Teleport​

Install Teleport on your OCI Compute instance.

Install Teleport on your Linux server:

  1. Assign edition to one of the following, depending on your Teleport edition:

    EditionValue
    Teleport Enterprise Cloudcloud
    Teleport Enterprise (Self-Hosted)enterprise
    Teleport Community Editionoss

  2. Get the version of Teleport to install. If you have automatic agent updates enabled in your cluster, query the latest Teleport version that is compatible with the updater:

    TELEPORT_DOMAIN=example.teleport.com
    TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Otherwise, get the version of your Teleport cluster:

    TELEPORT_DOMAIN=example.teleport.com
    TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')"

  3. Install Teleport on your Linux server:

    curl https://cdn.teleport.dev/install-v15.4.11.sh | bash -s ${TELEPORT_VERSION} edition

    The installation script detects the package manager on your Linux server and uses it to install Teleport binaries. To customize your installation, learn about the Teleport package repositories in the installation guide.

Step 4/5. Configure your services​

The Oracle join method can be used for Teleport processes running the SSH (Node), Proxy, Kubernetes, Application, Database, or Windows Desktop Services. The Teleport process should be run directly on an OCI Compute instance.

Configure your Teleport process with a custom teleport.yaml file. Use the join_params section with token_name matching your token created in Step 1 and method: oracle as shown in the following example config:

# /etc/teleport.yaml
version: v3
teleport:
  join_params:
    token_name: oracle-token
    method: oracle
  proxy_server: https://teleport.example.com:443
ssh_service:
  enabled: yes
auth_service:
  enabled: no
proxy_service:
  enabled: no

Step 5/5. Launch your Teleport process​

Configure your Teleport instance to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed your Teleport instance.

On the host where you will run your Teleport instance, enable and start Teleport:

sudo systemctl enable teleport
sudo systemctl start teleport

You can check the status of your Teleport instance with systemctl status teleport and view its logs with journalctl -fu teleport.

Once you have started Teleport, confirm that your service is able to connect to and join your cluster.