Access your infrastructure

OpsCanvas makes it easy to access your infrastructure and application components by providing a CLI that does the heavy lifting of finding, authenticating, configuring, and connecting.

Using the OpsCanvas CLI

The CLI allows you to:

  • Find and connect to Kubernetes Clusters. It assumes the OpsCanvas-Deploy-Role in the background which has cluster access.

  • Find account and user information

  • Port forward to cloud infrastructure inside private networks

Installing:

For Linux and macOS:

  1. Download the archive For macOS:

    wget https://oc-cli-release.s3.amazonaws.com/releases/latest/oc_Darwin_x86_64.tar.gz

    For Linux:

    wget https://oc-cli-release.s3.amazonaws.com/releases/latest/oc_Linux_x86_64.tar.gz
  2. Extract the archive For macOS:

    tar -xzf oc_Darwin_x86_64.tar.gz

    For Linux:

    tar -xzf oc_Linux_x86_64.tar.gz
  3. Move the executable to a directory in your PATH:

    sudo mv oc /usr/local/bin
  4. Validate the download with the checksum: This command will compare the checksum of the downloaded file with the one hosted with the file downloaded. If the checksums match, you will see a message indicating that the file is valid.

    wget https://oc-cli-release.s3.amazonaws.com/releases/latest/oc_Linux_x86_64.tar.gz (if not already downloaded)
    wget https://oc-cli-release.s3.amazonaws.com/oc/releases/latest/oc_1.1.0_checksums.txt
    sha256sum -c --ignore-missing oc_1.1.0_checksums.txt
  5. Verify the installation:

    oc info

For Windows:

  1. Download the archive:

    Invoke-WebRequest -Uri "https://oc-cli-release.s3.amazonaws.com/releases/latest/oc_Windows_x86_64.zip" -OutFile "oc_Windows_x86_64.zip"
  2. Extract the archive:

    Expand-Archive -Path "oc_Windows_x86_64.zip" -DestinationPath "."
  3. Move the executable to a directory in your PATH:

    Move-Item -Path ".\oc.exe" -Destination "C:\Program Files\oc\oc.exe"
    [Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Program Files\oc", [EnvironmentVariableTarget]::Machine)
  4. Verify the installation:

    oc info

Usage:

The OpsCanvas CLI will use your current AWS account to authenticate. Please ensure you either have AWS credentials to the target account, set in environment variables or as a profile set to point to credentials or an SSO account (i.e. export AWS_PROFILE=...). You can create a new profile and set a default region by running aws configure --profile <choose a name>

  1. Set your AWS account credentials, by setting your AWS profile to use by running export AWS_PROFILE=<your profile>, or have default credentials set. These are what the CLI will use.

  2. Run the various commands below.

Example use case:

  1. App is deployed in OpsCanvas

  2. You need to connect to its Kubernetes cluster to view something, so you download and install the CLI, and set your local AWS credentials/profile.

  3. Instead of typing a variety of aws cli commands to add the cluster, and assume a role that has access, you can simply type oc cluster. You will be given a list of the clusters in the account.

  4. Select a cluster, and it will add that cluster to your kubeconfig, set its context to that, and give you credentials to assume so you can use the role that has access.

Here are all the commands:

Show info about the current cloud user/account

Shows an aggregate of key info including account number, user, and Kubernetes context.

oc info

Connect to a cluster

Lists clusters to connect to, and when one is selected it adds it to kubeconfig and sets as current context on your machine. Then, credentials to assume the role that has access to the cluster are outputted, and simply need to be pasted into your terminal.

oc cluster

Add all clusters

Adds all EKS clusters found to your kubeconfig, and sets the first as current context on your machine. Then, credentials to assume the role that has access to the cluster are outputted, and simply need to be pasted into your terminal.

oc ar

Select a private cloud resource to port forward to (i.e. list, and select RDS database in private VPC):

oc port-forward

Explicitly specify resource to port forward to:

oc port-forward database-1-instance-1 5433:5432

Operation Reference

Here are some commonly used manual commands for gaining access to your application infrastructure without the CLI.

You will need to retrieve the following info from the OpsCanvas app. From Find environment info collect:

  • Account Id

  • Role

Assume role with access

In order to access infrastructure you must assume the role of an account that has rights in the cloud that houses the deployed application environment. You will need to assume the role each time you want to access the cluster.

OpsCanvas uses a role called OpsCanvas-Deploy-Role which you can set up to assume for this purpose. You must update the role's trust and your account policies to assume it.

aws sts assume-role \
--role-arn arn:aws:iam::<account_id>:role/<role> \
--role-session-name $USER

Note: on a unix-esque system, this will name the session after your logged-in user.

Update the Kubernetes config file

This step only needs to be done once. It creates an entry in your ~/.kube/config file.

aws eks \
--region <region> \
update-kubeconfig \
--name <cluster_name> \
--alias <something easy to type that is descriptive> \
--profile <cluster_name>

Optional: alias kubectl

It can become cumbersome to type kubectl a lot, a common trick is to alias it to k, add the following line in ~/.profile (create the file if it doesn't already exist)

alias k=kubectl

You can run source ~/.profile to have the changes take effect in the current shell

NOTE: in the discussion that follows "alias" refers to the cluster alias set in the previous step, and not the unix command "alias" shown above.

Optional: set the default namespace

Adding a default namespace for the cluster makes life a bit easier, as you don't need to include it every time you call kubectl.

The environment type can be found on the tile for the environment you are configuring:

k config set-context --cluster='<alias>' --namespace='<environment type>'

NOTE: setting the kubectl context is not the same as selecting it.

Select the kubectl context

Kubectl works with one cluster at a time, the selected cluster is called the context and that is the cluster kubectl commands will execute against.

You can view the list of contexts with k config get-contexts the starred context is the current one.

You can also view the current context with k config current-context.

To use the context, run k config use-context <alias>.

FWIW - we find the set-context vs. use-context a little confusing, but setting the context refers to updating kubectl's internal configuration, e.g. setting information about the particular context. Since no one asked, we'd prefer update-context and select-context.

Verify

To ensure everything is configured run k get pods to see a list of containers running in your environment.

NOTE: there is an additional "jump-pod" that can be used for console access into your cluster that can be used to access managed services that were provisioned for this environment.

Last updated