Note:

• This tutorial requires access to Oracle Cloud. To sign up for a free account, see Get started with Oracle Cloud Infrastructure Free Tier.
• It uses example values for Oracle Cloud Infrastructure credentials, tenancy, and compartments. When completing your lab, substitute these values with ones specific to your cloud environment.

Connect to an Oracle Cloud Infrastructure Kubernetes Engine cluster using Local Access

Introduction

In this tutorial, we will guide you through connecting to an Oracle Cloud Infrastructure Kubernetes Engine (OCI Kubernetes Engine or OKE) cluster using Local Access. By the end of this tutorial, you will be able to configure your local machine to interact with your OKE cluster securely and efficiently. This connection method is essential for managing your cluster resources, deploying applications, and troubleshooting runs from your local environment. Whether you are a beginner or experienced with Kubernetes, this step-by-step approach will ensure a smooth and straightforward setup.

When you look at the networking part of the Kubernetes cluster you have different Kubernetes network architectures that can be used for deployment. For more information, see Example Network Resource Configurations.

Sometimes you want to deploy the API endpoint with a private IP address and when you do this the Kubernetes cluster cannot be managed using OCI Cloud Shell application, and also not from another machine connected to the internet. You need to select Local Access, but before we can connect with the local access we first need to set up an instance that can act as a bastion.

Objectives

• Connect to an Oracle Cloud Infrastructure Kubernetes Engine cluster using Local Access.

Task 1: Verify a Kubernetes Cluster

Make sure you have a deployed Kubernetes cluster on OCI OKE.

• To deploy Kubernetes cluster on OKE, use one of the following methods:

  • Task 1: Create a New Kubernetes Cluster and Verify the Components: Deploy a Kubernetes cluster on OKE using the Quick Create mode.

  • Task 1: Deploy a Kubernetes Cluster using OKE: Deploy a Kubernetes cluster on OKE using the Custom Create mode.

  • Use Terraform to Deploy Multiple Kubernetes Clusters across different OCI Regions using OKE and Create a Full Mesh Network using RPC: Deploy multiple Kubernetes cluster on multiple regions on OKE using Terraform.

  • Deploy a Kubernetes Cluster with Terraform using Oracle Cloud Infrastructure Kubernetes Engine: Deploy a single Kubernetes cluster on OKE using Terraform.

• Log in to the OCI Console, navigate to Developer Services, Kubernetes Clusters (OKE) and click the cluster.

  

• Click Access Cluster.

  

• Select Local Access. Copy the following commands that you will need once the bastion has been created and configured correctly.

  

Task 2: Create a new Linux Instance to act as Bastion

In this task, we will deploy a bastion instance in a public subnet, but when using the OCI Bastion service and session (later in this tutorial) it is better to deploy the bastion instance on a private subnet. In this tutorial, we are not doing this because we want to showcase the flexibility and various different options.

Task 2.1: Create a bastion-private-sec-list Security List with Ingress and Egress Rule

Determine the new subnet where the new bastion instance is going to be in 10.0.5.0/24. We need this to create the security lists properly.

• Go to the OCI Console, navigate to Networking, Virtual Cloud Networks and select the VCN where your Kubernetes cluster is deployed.

  1. Click Security Lists.
  2. Click Create Security List.
  3. Enter a security list Name.
  4. Click + Another Ingress Rule.

  

• Enter the following information to create the Ingress Rule 1.

  1. Source Type: Enter CIDR.
  2. Source CIDR: Enter the source to be the subnet of the bastion instance (10.0.5.0/24).
  3. IP Protocol: Enter TCP.
  4. Destination Port Range: Enter 22.
  5. Click + Another Ingress Rule.

  

• Enter the following information to create Ingress Rule 2.

  1. Source Type: Enter CIDR.
  2. Source CIDR: Enter the source to be the subnet of the bastion instance (10.0.5.0/24).
  3. IP Protocol: Enter ICMP.
  4. Scroll down.

  

• Click + Another Egress Rule.

  

• Enter the following information to create Egress Rule 1.

  1. Destination Type: Enter CIDR.
  2. Destination CIDR: Enter the source to be everything (0.0.0.0/0).
  3. IP Protocol: Enter All Protocols.
  4. Click Create Security List.

  

• Note that the new security list has been created, click the security list and verify the rules.

  

  1. Click Ingress Rules.
  2. Note that the rules are present.

  

  1. Click Egress Rules.
  2. Note that the rule is present.

  

Task 2.2: Create a bastion-public-sec-list Security with Ingress and Egress Rules

• Click Create Security List.

  

  1. Enter a security list Name.
  2. Click + Another Ingress Rule.

  

• Enter the following information for Ingress Rule 1.

  1. Source Type: Enter CIDR.
  2. Source CIDR: Enter the source to be the subnet of the bastion instance (10.0.5.0/24).
  3. IP Protocol: Enter ICMP.
  4. Click + Another Ingress Rule.

  

• Enter the following information for Ingress Rule 2.

  1. Source Type: Enter CIDR.
  2. Source CIDR: Enter the source to be everything (0.0.0.0/0).
  3. IP Protocol: Enter TCP.
  4. Destination Port Range: Enter 22.
  5. Click + Another Ingress Rule.

  

• Enter the following information for Ingress Rule 3.

  1. Source Type: Enter CIDR.
  2. Source CIDR: Enter the source to be everything (0.0.0.0/0).
  3. IP Protocol: Enter ICMP.
  4. Click + Another Egress Rule.

  

• Enter the following information for Egress Rule 1.

  1. Destination Type: Enter CIDR.
  2. Destination CIDR: Enter the source to be everything (0.0.0.0/0).
  3. IP Protocol: Enter All Protocols.
  4. Click Create Security List.

  

• Note that the new security list has been created, click the security list and verify the rules.

  

  1. Click Ingress Rules.
  2. Note that the rules are present.

  

  1. Click Egress Rules.
  2. Note that the rule is present.

  

Task 2.3: Create the bastion-route-table with Internet Gateway to Add to the Bastion Instance for Internet Access

Note: Make sure that you have created an internet gateway in the VCN.

• Go to the Virtual Cloud Networks Details page.

  1. Click Route Tables.
  2. Click Create Route Table.

  

  1. Enter a Name.
  2. Click + Another Route Rule.

  

• In the Rule section, enter the following information.

  1. Target Type: Select Internet Gateway.
  2. Destination CIDR Block: Enter 0.0.0.0/0.
  3. Target Internet Gateway: Select the existing internet gateway.
  4. Click Create.

  

• Note that the new route table has been created, click the route table and verify the rules.

  

  1. Note that the rule is present.
  2. Click the VCN to go back to the VCN page.

  

Task 2.4: Create a Regional Public Subnet (bastion-subnet) for the Bastion Instance 

• Click Subnets.

  

• Click Create Subnet and enter the following information.

  1. Enter a Name.
  2. Subnet Type: Select Regional.
  3. IPv4 CIDR Block Enter 10.0.5.0/24.
  4. Scroll down.

  

  1. Route Table: Select the route table created in Task 2.3.
  2. Subnet Access: Select Public Subnet.
  3. Scroll down.

  

  1. Dhcp Options Compartment: Select the default DHCP Options.
  2. Security Lists: Select the security list created in Task 2.2 for the public subnet.
  3. Click Create Subnet.

  

• Note that the new subnet has been created.

  

Task 2.5: Add the bastion-private-sec-list to the Worker Private Subnet to Access the Worker Nodes by Bastion Instances

• Go to the Virtual Cloud Networks Details page.

  1. Click Subnets.
  2. Click the subnet where your Kubernetes worker nodes are connected.

  

  1. Click Security Lists.
  2. Click Add Security List.

  

  1. Security List: Select the security list for the private subnet created in Task 2.1.
  2. Click Add Security List.

  

• Note that the security list is added to the (Kubernetes worker node) subnet.

  

Task 2.6: Create OCI Compute Instance

Create the bastion instance.

• Go to the OCI Console, navigate to Compute, Instances and click Create Instance.

  

  1. Enter a Name.
  2. Scroll down.

  

• Scroll down.

  

  1. Select VCN that you used to create the subnet in Task 2.4.
  2. Select Subnet created in Task 2.4.

  

• Scroll down.

  

  Note: In this example, we have used an existing public key. You can also choose to Generate the Key pair, but if you do this make sure you save it, because you will need it later. To create an instance with the Generate a key pair, see Create Your First Linux Compute Instance Using Oracle Cloud Infrastructure.

• In the Create compute instance page, enter the following information.

  1. Select Upload public key files.
  2. Click Browse.
  3. Make sure an existing public key is selected.
  4. Scroll down.

  

• Click Create.

  

• Note that the instance shows PROVISIONING state.

  

Task 2.7: Get the Public IP Address of the Bastion Instance (BastionHost) to SSH

• Go to the Instance details page.

  1. When the instance is fully deployed it will show RUNNING state.
  2. Copy Public IP address.

  

Task 2.8: Log in to the Bastion Host

• Open a terminal or another application that you can use to set up SSH connections and run the following command.

  1. Change the directory to where your private and public key is stored.
  2. Run the following command to connect with SSH to the instance public IP address using the private key.
  3. Enter yes to continue.
  4. Note that you are now logged in to the instance.
  5. Run the following command to get the private IP address of the instance.
  6. Note that the instance has an IP address of 10.0.5.62/24 which is in the subnet of 10.0.5.0/24.

  

Task 3: Create a Bastion Session

We can use the bastion instance as a standalone host, but we can also make use of the bastion service or bastion session. To do this we need to install the bastion plugin and create a bastion session.

What are the benefits of a bastion session?

When you deploy an instance within a private subnet, it is not directly accessible from the internet. However, by setting up a bastion and initiating a bastion session, you can make the private instance accessible. This allows the instance to act as a stepping stone for managing other resources within your OCI environment.

Task 3.1: Install the Bastion Plugin on the Instance

• Go to the instance created in Task 2.6.

  1. Click Oracle Cloud Agent.
  2. Scroll down.

  

  1. Set the bastion to Enabled.
  2. The service is set to Stopped. This will change after a few minutes.

  Note:

  • To deploy the bastion plugin, the instance needs to have access to the Internet through a NAT gateway or internet gateway, as the plugin is downloaded from the Internet. When the plugin status remains in the Stopped state, check your internet connectivity.
  • You can also manually install the Oracle Cloud Agent Software. For more information, see Installing the Oracle Cloud Agent Software.

  

• When the Oracle Cloud Agent Software is installed the status will change to Running.

  

Task 3.2: Create the Bastion Session

• Navigate to Identity, Security and click Bastion.

  1. Click Create bastion.

  

• Enter the following information.

  1. Bastion name: Enter a name.
  2. Target virtual cloud network: Select the VCN where the bastion instance and the Kubernetes cluster are present.
  3. Target subnet: Select the subnet where your bastion instance is located.
  4. CIDR block allowlist: Select an allowlist. To allow everything use 0.0.0.0/0.
  5. Click Create bastion.

  

• Note that the bastion status is Creating.

  

  1. After a few minutes the bastion status will change to Active.
  2. Click the bastion.

  

• Click Create session.

  

• Enter the following information.

  1. Session type: Select Managed SSH session.
  2. Session name: Enter a name.
  3. Username: Enter the username of the bastion instance.
  4. Compute instance: Select the bastion instance created in Task 2.6.
  5. Add SSH key: Select Choose SSH key file.
  6. Click browse.
  7. Make sure you select the public key of the bastion instance created in Task 2.6.
  8. Click Create session.

  Note: In this example, we are using the same SSH key pair that we have used for the bastion instance for simplicity reasons. We suggest you to create or use a key pair that is different from the one you used for the bastion instance.

  

Task 3.3: Get the SSH Command of the Bastion Session

• Go to the bastion details page.

  1. Note that the Bastion Session is created.
  2. Click the three dots menu.
  3. Select Copy SSH command.

  

Task 3.4: Log in to Bastion Host

• Open a terminal or another application that you can use to set up SSH connections and run the following command.

1. Run the following copied SSH command in the terminal.
2. Enter yes to continue for the bastion SSH session.
3. Enter yes to continue for the instance SSH session.
4. Note that you are now logged in to the instance through a bastion session.

Note: This is a different way of connecting to the bastion instance that we showed. Now we are connecting to the bastion instance through a bastion session, and earlier we connected directly with SSH to the bastion instance.

Task 4: Set up OCI Command Line Interface (CLI)

We have successfully set up the bastion instance, the bastion, and the bastion session and we have verified connectivity, we now need to set up OCI CLI so we are able to perform CRUD (create, read, update, and delete) operations inside our OCI environment.

• Run the following command to update the software that is already installed.

  [opc@oke-bastion-instanc ~]$ sudo dnf update
  

  

• Enter y to confirm the update.

  

• Note that the update is Complete!.

  

  1. Run the following command to install Oracle Developer Release.

     [opc@oke-bastion-instanc ~]$ sudo dnf -y install oraclelinux-developer-release-el8
     

  2. In this example, Oracle Developer Release is already installed. If not in your case, install it.

  

  1. Run the following command to install OCI CLI.

     [opc@oke-bastion-instanc ~]$ sudo dnf install python36-oci-cli
     

  2. Enter y to confirm the installation.

  

• Note that the installation is complete!.

  

  1. Run the following command to verify the installed OCI CLI version.

     [opc@oke-bastion-instanc ~]$ oci -v
     

  2. Note that the OCI CLI version is 3.49.0.

  

Task 5: Configure OCI CLI

We need to add some configuration to make sure the OCI CLI is able to authenticate on your OCI tenant so you are able to perform CRUD operations.

• Run the following commands to create a new hidden directory inside your home folder.

  [opc@oke-bastion-instanc ~]$ mkdir  ~/.oci/
  

• Run the following command to change the directory to the one you just created.

  [opc@oke-bastion-instanc ~]$ cd  ~/.oci/
  

• Run the following command to generate a new key pair (public and private key). In this tutorial, we are not using any passwords so we will enter N/A at the passphrase question.

  [opc@oke-bastion-instanc .oci]$ oci setup keys
  

• Run the following command to verify if your key pair has been generated successfully.

  [opc@oke-bastion-instanc .oci]$ ls -l
  

  

• Run the following command to get the content of the public key. Make sure you copy because you will need it later.

  [opc@oke-bastion-instanc .oci]$ cat ~/.oci/oci_api_key_public.pem
  

  

  1. Go to the OCI Console, click the profile icon.
  2. Click My Profile.

  

• Scroll down.

  

  1. Click API keys.
  2. Click Add API key.

  

  1. Select Paste a public key.
  2. Paste the public key collected from the bastion instance.

  

  1. Copy the configuration file.
  2. Click Close.

  

• This is an output of the copied configuration. You need to change the <path to your private keyfile> value with the one you just generated.

  [DEFAULT]
  user=ocid1.user.oc1..aaaaaaaavgrv6wsnnzhtwpjmyqtdqbq7kacfdfooz5uta3ludvfuwibe23aq
  fingerprint=a7:ff:fb:20:18:75:31:7d:b0:7c:04:8f:0c:cb:98:23
  tenancy=ocid1.tenancy.oc1..aaaaaaaabh2affulc4dt4tqs7lbojyhqi6hzn5mjllxlnuqnletufsofoyvq
  region=eu-frankfurt-1
  key_file=<path to your private keyfile> # TODO
  
  

• Run the following command to create the OCI CLI config file.

  [opc@oke-bastion-instanc .oci]$ nano ~/.oci/config
  

  1. Copy the content of the configuration provided by the OCI Console in the config file.
  2. Change the private key file location.

  [DEFAULT]
  user=ocid1.user.oc1..aaaaaaaavgrv6wsnnzhtwpjmyqtdqbq7kacfdfooz5uta3ludvfuwibe23aq
  fingerprint=a7:ff:fb:20:18:75:31:7d:b0:7c:04:8f:0c:cb:98:23
  tenancy=ocid1.tenancy.oc1..aaaaaaaabh2affulc4dt4tqs7lbojyhqi6hzn5mjllxlnuqnletufsofoyvq
  region=eu-frankfurt-1
  key_file=~/.oci/oci_api_key.pem
  

• Make sure you save and exit from the config file.

  

• Run the following command to make sure the config file is created.

  [opc@oke-bastion-instanc .oci]$ ls -l
  

  

  Note: For more information, see Oracle Cloud Infrastructure CLI Command Reference.

  1. Run the following command to review all resource types that are configured in your tenant.

     [opc@oke-bastion-instanc .oci]$ oci search resource-type list --all --output table --query "data [*].{Name:name}"
     

  2. Note that the warning that shows permissions on the config file are too open, we will fix this.

  3. Note the output of all the resource types that are configured in your tenant.

  

  

• Run the following command to fix the file permissions of the config file.

  [opc@oke-bastion-instanc .oci]$ oci setup repair-file-permissions --file /home/opc/.oci/config
  

  

  1. Run the following command to retrieve a list of all the regions where your tenant is subscribed.

     [opc@oke-bastion-instanc .oci]$ oci iam region list
     

  2. Note the output of all the regions to which your tenant is subscribed.

  

  1. Run the following command to list all the configured compartments in your tenant.

     [opc@oke-bastion-instanc .oci]$ oci iam compartment list
     

  2. Note the output of all the compartments of your tenant.

  

Task 6: Use OCI CLI in Interactive Mode

• You can also use OCI CLI in interactive mode. This way OCI CLI will provide you the commands and next keywords in the command that you can use to eventually get your full command that you require. For more information, see Using Interactive Mode.

  1. Run the following command to start OCI CLI in interactive mode.

  [opc@oke-bastion-instanc .oci]$ oci -i
  

  1. You can see OCI CLI interactive mode prompt.
  2. Press Tab to autocomplete commands, Enter to execute command, and Ctrl + D to quit the interactive mode.

  

  1. Enter Tab to get the first level of commands.
  2. Note the available first level of commands.

  

• Enter ia and press Tab key to show the available command options.

  

• Enter iam compartment and press the Tab key to show the available command options.

  

• Press Tab key to autocomplete the word compartment. So you now have the command iam compartment.

  

• Press Tab key to show the next available option for the iam compartment command.

  

  1. Run the iam compartment list command.
  2. Note the output of all the compartments of your tenant.

  

Task 7: Access the Kubernetes Cluster using OCI CLI

• Run the following command to check the OCI CLI version.

  oci -v
  

• Access the Kubernetes cluster.

  1. Create a directory to contain the kubeconfig file.

     mkdir -p $HOME/.kube
     

  2. To access the kubeconfig file for your cluster through the VCN-Native public endpoint, copy the following command.

     oci ce cluster create-kubeconfig --cluster-id ocid1.cluster.oc1.eu-frankfurt-1.aaaaaaaagwiamspaz7h4pxxxxxxxxxxxxxxxj75gd7chc27su6o56kq --file $HOME/.kube/config --region eu-frankfurt-1 --token-version 2.0.0  --kube-endpoint PUBLIC_ENDPOINT
     

  3. Run the following command to set your KUBECONFIG environment variable to the file for this cluster.

     export KUBECONFIG=$HOME/.kube/config
     

  

  1. Run the following command to download the latest Kubernetes release.

     [opc@oke-bastion-instanc ~]$ curl -LO "https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl"
     

  2. Run the following command to make the kubectl application executable.

     [opc@oke-bastion-instanc ~]$ chmod +x ./kubectl
     

  3. Move the kubectl application to a location where the $PATH variable is active, so that you can run the kubectl command from anywhere.

     [opc@oke-bastion-instanc ~]$ sudo mv ./kubectl /usr/local/bin/kubectl
     

  

  1. Run the following command to get your Kubernetes cluster information.

     [opc@oke-bastion-instanc ~]$ kubectl cluster-info
     

  2. Run the following command to get the Kubernetes client and server versions.

     [opc@oke-bastion-instanc ~]$ kubectl version
     

  3. Run the following command to get all the worker nodes that are part of the Kubernetes cluster.

     [opc@oke-bastion-instanc ~]$ kubectl get nodes
     

  

Next Steps

Connecting to your OKE cluster using the local access allows you to manage and interact with your cluster resources from your local environment with ease. By following the tasks outlined in this tutorial, you have set up a secure connection and can now deploy, monitor, and maintain applications on your OKE cluster. With this set up, you are equipped to handle administrative tasks, troubleshoot runs, and optimize your workflows efficiently. Keep these configurations handy for future reference, and feel free to explore further customization options to suit your specific needs.

Acknowledgments

• Author - Iwan Hoogendoorn (OCI Network Specialist)

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.

---

Title and Copyright Information

Connect to an Oracle Cloud Infrastructure Kubernetes Engine cluster using Local Access

G18240-01

November 2024

Copyright ©2024,

Oracle and/or its affiliates.