Orka on AWS: Orka CLI Login

How to authenticate on an AWS instance to your Orka on AWS cluster.


Quick navigation

Time to read: 2 minutes, 28 seconds

Jump to: Set up port forwarding | Access the Orka VM UI

See also: Getting started | Initial configuration guide | Known limitations | Accessing the Orka Web UI

For security reasons, you can access your Orka cluster only from within your customer VPC. The Orka CLI requires a browser in order to complete authentication. By default, Amazon does not provide a UI for your customer instances which means that you need to login from your local machine. To do that and work with your Orka CLI, you need to configure port forwarding. You will need to direct traffic from a specified available port on your local machine to a bastion host or instance in your customer VPC, which will then save your login token on its local disk.

Before you begin

  1. Download and install the latest Orka3 CLI on the bastion host in your customer VPC.
    • On Linux, unpack the archive and move the executable to /usr/local/bin.
    • On Windows, add the directory of the executable to your PATH.
  2. On your bastion host, configure the Orka API by running:
orka3 config set --api-url <ORKA_API_URL>

This operation is a one-time effort. With it, you set the Orka service endpoint for your cluster.

Initiate the login procedure

  1. On your bastion host, run the following command
orka3 login

This outputs the following:

  1. From the URL from step 1, note down the remote port to use for port forwarding. By default, it is 51234. This can be taken from the redirect_uri=http%3A%2F%2Flocalhost%3A51234parameter in the URL. The port is at the end of the parameter.
  2. Note down the whole URL from step 1.

Set up port forwarding



Never use the customer account root user when working with your Orka VPC.

You can use the AWS CLI (recommended) or SSH to configure port forwarding.

  1. Before you begin, obtain the following information:

    • <customer_vpc_region> (if using the AWS CLI): The code of the region of your customer VPC.
    • <customer_vpc_host_id> (if using the AWS CLI) or <customer_vpc_host> (if using SSH): Respectively, the ID or IP of a bastion host or an instance in your customer VPC. For more information about how to obtain the ID or the IP, see here.
    • <remote_login_port>: The port obtained in step 2 during thelogin procedure initiation. By default, it is 51234.
    • <local_port>: Must be the same as the <remote_login_port>.
  2. (Recommended) If you have configured AWS Systems Manager (AWS SSM) for your customer VPC and you have installed the AWS CLI on your local machine, you can run the following command.

aws ssm start-session --region <customer_vpc_region> \
    --target <customer_vpc_host_id> \
    --document-name AWS-StartPortForwardingSessionToRemoteHost \
    --parameters '{"host":["localhost"],"portNumber":["<remote_login_port>"],"localPortNumber":["<local_port>"]}'
  1. Otherwise, you can enable port forwarding via SSH.
ssh -L <local_port>:localhost:<remote_login_port> "UserKnownHotsFile=/dev/null" -o "StrictHostKeyChecking=no" <customer_vpc_host>


Once you have the port forwarding set up:

  1. Open the URL obtained in step 1 during thelogin procedure initiation.
  2. Enter your credentials for the MacStadium Customer Portal and click Sign In. Your authentication token is saved on the bastion host in your customer VPC.
  3. Go back to your bastion host. The Orka CLI is fully configured and you can run commands against the Orka cluster.



If several users are using the bastion host at the same time, they can override each others tokens. To prevent that, ensure each user has its own account in the bastion host and they run all Orka CLI commands from that account.

© 2019-2023 Copyright MacStadium, Inc. – Documentation built with readme.com. Orka is a registered trademark of MacStadium, Inc.