Prepare OCI Tenancy for the REAL OCI Katacoda Scenarios

This and the next preparatory steps can (only) be performed by the user who is the tenancy owner or by another user who is member of Administrators Group. In this step, you will create a config file and a public/private key pair - required by the OCI CLI tool that you will be using in the other scenarios. You will use the Cloud Shell tool to get easy command line access to a number of tenancy specific values that are need for the config and private key files.

Retrieve Configuration Values and Private Key

In the scenarios you will be using the OCI CLI (command line interface) on many occasions. You will use fairly simple, straightforward terminal commands with this CLI. This tool in turn interacts with the OCI REST APIs for querying and manipulating OCI resources. OCI CLI needs to be enabled to connect to your tenancy: it needs to know where your OCI tenancy is and how to connect to it. For this, two files need to be prepared:

• ~/.oci/config
• ~/.oci/oci-api-key.pem

Empty versions of these two files are created as part of every scenario in this series. Look in the file explorer in directory /root/.oci for these two files. Click on config to open the empty file.

Here is an example of what the config file will look like; click on Copy to Editor to copy this content to the config file:

[DEFAULT]
user=OCID FOR YOUR TENANCY OWNER USER OR OTHER ADMIN USER
fingerprint=FINGERPRINT FOR KEY FOR USER
tenancy=OCID FOR YOUR TENANCY
region=HOME REGION OF YOUR TENANCY
key_file=/root/.oci/oci_api_key.pem

This step in the scenario will help you prepare these files and to add the public key half of the key pair you will generate to the OCI user. The private key half is used to make the OCI CLI work with OCI as the user.

Gather Configuration Values in Cloud Shell

Login to the OCI Cloud Console as the tenancy owner (or a user who is administrator).

Open the OCI Cloud Shell tool, from the OCI Cloud Console.

Note: For clipboard operations, Windows users can use Ctrl-C or Ctrl-Insert to copy, and Shift-Insert to paste. For Mac OS users, use Cmd-C to copy and Cmd-V to paste.

Execute these commands in Cloud Shell to retrieve the OCID (Oracle Cloud Identifier) of the tenancy and the OCID of your user into environment variables, as well as the Region (name and key):

export TENANCY_OCID=$(oci iam user list --all | jq -r  '.data[0]."compartment-id"') 
export USER_OCID=$(oci iam user list --all | jq -r  '.data |sort_by(."time-created")| .[0]."id"')
export REGION=$(oci iam region-subscription list | jq -r '.data[0]."region-name"')
export REGION_KEY=$(oci iam region-subscription list | jq -r '.data[0]."region-key"')

Let's see if all values have been set as expected; execute this command in Cloud Shell:

__config="user=$USER_OCID
tenancy=$TENANCY_OCID
region=$REGION
"
echo "$__config"

You should now see values for user, tenancy and region. If not all of these three have a value, please repeat the the previous commands. ### Generate Public & Private Key pair in Cloud Shell Then - still in Cloud Shell - use the following statements to generate the key pair, upload the public key to the OCI user resource and retrieve the public key fingerprint:

mkdir ~/oci-keys
openssl genrsa -out ~/oci-keys/oci_api_key.pem 2048
# generate public key
openssl rsa -pubout -in ~/oci-keys/oci_api_key.pem -out ~/oci-keys/oci_api_key_public.pem
# add public key to the OCI admin user
oci iam user api-key upload --user-id $USER_OCID  --key-file ~/oci-keys/oci_api_key_public.pem
# get fingerprint
export KEY_FINGERPRINT=$(oci iam user api-key list --user-id  $USER_OCID  | jq -r '.data[0]."fingerprint"')

Edit Config and Private Key File in Katacoda

You will now use the results of the actions in Cloud Shell for completing the configuration and private key file in Katacoda.

Config File

In Cloud Shell, execute this command, to get the contents for the config file:

__config="[DEFAULT]
user=$USER_OCID
fingerprint=$KEY_FINGERPRINT
tenancy=$TENANCY_OCID
region=$REGION
key_file=/root/.oci/oci_api_key.pem
"
echo "$__config"

Select the output from this command in Cloud Shell and copy it to the clipboard (through right mouse menu or using Ctrl-C or Ctrl-Insert in Windows and Cmd-C on Mac OS).

Back in the Katacoda scenario: open file ~/.oci/config in the text editor, and paste the contents from the clipboard into the file.

Private Key File

In Cloud Shell, execute this command to list the contents of the private key and copy the contents to the clipboard.

cat ~/oci-keys/oci_api_key.pem

Note: this is the private key that no one but you should have access to. We only need to show the contents so you can copy it to the clipboard and paste into a file in the Katacoda scenario.

Back in the Katacoda scenario: open file ~/.oci/oci-api-key.pem in the text editor, and paste the contents from the clipboard into the file.

Try out the OCI CLI connection to your Tenancy

To make sure that the config file and the oci-api-key.pem file have the correct contents, try out the following command to get a list of all namespaces you currently have access to - based on the OCI Configuration defined above.

oci os ns get

If this command gives a proper response, the configuration is most likely correct.

Another test - listing all users in your OCI tenancy:

oci iam user list --all

Set environment variables in the Katacoda environment with the Tenancy OCID, the region name and the region key:

export TENANCY_OCID=$(oci iam user list --all | jq -r  '.data[0]."compartment-id"')
export REGION=$(oci iam region-subscription list | jq -r '.data[0]."region-name"')
export REGION_KEY=$(oci iam region-subscription list | jq -r '.data[0]."region-key"')

Note: the following syntax will be used to use the lowercase value for region: echo ${REGION,,}

Auth Token for OCIR (Container Registry)

For working with Functions, you need an auth token for working with the OCI Container Registry. The next script generates such a token for the tenancy owner (the oldest user in the tenancy). Please record this token for use in the scenarios that work with functions. Note: you can find these tokens in the console as well: https://console.us-ashburn-1.oraclecloud.com/identity/users//swift-credentials.

Execute this command to generate the Auth Token

USER_OCID=$(oci iam user list --all | jq -r  '.data |sort_by(."time-created")| .[0]."id"')
authTokenJS=$(oci iam auth-token create --description "Token for logging in into Docker/OCIR" --user-id $USER_OCID)
echo $authTokenJS
authToken=$(echo $authTokenJS | jq --raw-output .data.token)
echo "Token for logging in into Container Registry $authToken"
NAMESPACE=$(oci os ns get| jq -r  '.data')
USER_USERNAME=$(oci iam user list --all | jq -r  '.data |sort_by(."time-created")| .[0]."name"')
echo "Username for logging in into Container Registry is $NAMESPACE/$USER_USERNAME"

Note: Record the Auth Token and the Username for logging in into the Container Registry for future use.

Create Local Copies of Files config and oci-api-key.pem

You will need config and oci-api-key.pem files in almost every REAL Katacoda OCI scenario. You will be copying and pasting the contents of these files in each scenario. Therefore, now is a good time to prepare copies of these files, locally on your laptop. Note that the Katacoda environment is ephemeral: in less than 50 minutes, it will vanish.

Open file ~/.oci/config in the text editor, copy the contents and paste it to a local file on your laptop's file system. Make sure you will be able to find this file for the subsequent Katacoda scenarios.

In the same vein, Open file ~/.oci/oci-api-key.pem in the text editor, copy the contents and paste it to a local file on your laptop's file system. Make sure you will be able to find this file too for the subsequent Katacoda scenarios. Note: do not share this file with anyone: it contains the private key to your tenancy.

Create OCI Resources

The Lab environment uses a compartment called lab-compartment to hold all new OCI resources. When you are done with this scenario, the tenancy will have this compartment, set up like this:

The resources are created in the OCI tenancy - in the lab-compartment from the OCI CLI environment set up in the Katacoda scenario VM:

Create this compartment with the following commands:

compartment=$(oci iam compartment create --compartment-id "$TENANCY_OCID"  --name "lab-compartment" --description "Compartment for resources for REAL Cloud Native workshop")
echo "JSON response from the command to create the compartment:"
echo $compartment
compartmentId=$(echo $compartment | jq --raw-output .data.id)
echo The OCID for the lab compartment:  $compartmentId

To set an environment variable $compartmentId fetch the OCID from the compartment with this command (this also works when the compartment already existed prior to running this scenario):

cs=$(oci iam compartment list)
export compartmentId=$(echo $cs | jq -r --arg display_name "lab-compartment" '.data | map(select(."name" == $display_name)) | .[0] | .id')

Create Tag Namespace

Tags can be associated with OCI resources, to provide meta data for easier interpreting, finding, managing and operating on and for reporting and billing. Custom tags are in custom tag namespaces. The scenarios assume the existence of at least one tag namespace called lab-tags.

Execute this command to create the tag namespace lab-tags in compartment lab-compartment.

oci iam tag-namespace create --compartment-id $compartmentId --name "lab-tags"  --description "Tag Namespace for REAL OCI scenarios"

Create Virtual Cloud Network (aka VCN)

The Virtual Cloud Network defines the connections within and two resources in the lab-compartment. It consists of quite a few moving parts. Fortunately, the OCI Console provides a wizard that creates all these parts for us. Run the OCI Networking Quickstart wizard in the context of compartment lab-compartment – to create VCN, subnets, internet gateway, NAT gateway, service gateway.

Note: this wizard is available in the OCI Console: https://console.us-ashburn-1.oraclecloud.com/networking/vcns ; replace the section us-ashburn-1 with your tenancy's home region. If you execute the next command, the proper URL is printed in the terminal window and the url is clickable in the terminal echo "Open the console at https://console.${REGION,,}.oraclecloud.com/networking/vcns"

Make sure that the List Scope element in the lower left hand corner of the OCI Console window is set to lab-compartment.

The start the wizard.

Select the default option in th VCN wizard "VCN with Internet Connectivity" and press Start VCN Wizard.

Use as the name of the VCN: vcn-lab. Accept all examples for CIDR blocks and default settings elsewhere.

When the wizard is done run this statement to retrieve the OCID of the VCN that has been created, as well as the public subnet's id and the identifier of the security list created for the VCN:

vcns=$(oci network vcn list  --compartment-id $compartmentId --all)
export vcnId=$(echo $vcns | jq -r --arg display_name "vcn-lab" '.data | map(select(."display-name" == $display_name)) | .[0] | .id')
echo "$vcnId"
subnets=$(oci network subnet list  -c $compartmentId --vcn-id $vcnId)
export subnetId=$(echo $subnets | jq -r --arg display_name "Public Subnet-vcn-lab" '.data | map(select(."display-name" == $display_name)) | .[0] | .id')

sls=$(oci network security-list list  -c $compartmentId --vcn-id $vcnId)
export slOCID=$(echo $sls | jq -r '.data | .[0] | .id')

Define Network Security Rule to allow Inbound Traffic to Port 443

Add a network security rule to allow inbound traffic to public subnet on port 443. Note: this step is required for the use of the API Gateway.

oci network security-list update --security-list-id $slOCID --ingress-security-rules file://./network-security-list-ingress-rules.json --force

If you are curious, you can verify the network security list in the OCI Console: echo "Open the console at https://console.${REGION,,}.oraclecloud.com/networking/vcns/$vcnId/security-lists/$slOCID"

and the specific new ingress rule for incoming traffic on port 443:

Create API Gateway

Create an API Gateway called lab-apigw using the following command. Note how this gateway references the public subnet identifier of the VCN.

oci api-gateway gateway create --compartment-id $compartmentId --endpoint-type PUBLIC --display-name lab-apigw --subnet-id $subnetId

The feedback from OCI CLI will be that a workrequest is created for creating the API Gateway. The actual creation is a background process that will take from a few seconds to a few dozen seconds to complete.

Retrieve the API Gateway's OCID. Note: if no identifier is returned, you may have to wait a little longer until this command does return a value:

apigws=$(oci api-gateway gateway list -c $compartmentId)
export apiGatewayId=$(echo $apigws | jq -r --arg display_name "lab-apigw" '.data.items | map(select(."display-name" == $display_name)) | .[0] | .id')
echo "apiGatewayOCID = $apiGatewayId"

Create a Dynamic Group that will be used later on to allow the API Gateway access to functions it should route requests to. The Dynamic Group is called lab-apigw-dynamic-group and includes a matching rule that defines which resources are a member of the group (that would be all API Gateways, and of course specifically the one you have just created)

oci iam dynamic-group create --compartment-id $TENANCY_OCID --name "lab-apigw-dynamic-group" --description "to organize access for API Gateway to functions" --matching-rule "[ \"ALL {resource.type = 'ApiGateway', resource.compartment.id = '$compartmentId'}\"]"

Create a Stream for Storing Event Messages

Create a stream called lab-stream. A stream is Kafka compliant Message or Event Topic.

oci streaming admin stream create --name "lab-stream" -c $compartmentId --partitions 1

You can check the new stream in the OCI console if you feel so inclined: echo "To list all streams, open the console at https://console.${REGION,,}.oraclecloud.com/storage/streaming"{execute}

Create Policies to allow access on Lab Compartment

Policies in OCI are used to define permissions - rules about accessing resources or capabilities. In this step, you will create a few policies that allow the Functions service to access repositories and to use the Virtual Cloud Network in the lab-compartment. An additional policy is created to provide necessary access privileges to dynamic group lab-apigw-dynamic-group (and indirectly to the API Gateway); this access is limited to lab-compartment (the functions and virtual network in the compartment)

Policies to enable the Functions Services

Run this command to create two policies for the Functions service with regard to the Lab Compartments network and the Function Repos in the OCI container registry

echo creating policy lab-faas-use-network-family
oci iam policy create  --name lab-faas-use-network-family --compartment-id $TENANCY_OCID  --statements "[ \"Allow service FaaS to use virtual-network-family in compartment lab-compartment\"]"  --description "Create a Policy to Give the Oracle Functions Service Access to Network Resources"

echo creating policy lab-faas-read-repos
oci iam policy create  --name lab-faas-read-repos --compartment-id $TENANCY_OCID  --statements "[ \"Allow service FaaS to read repos in tenancy\"]"  --description "Create a Policy to Give the Oracle Functions Service Access to Repositories in Oracle Cloud Infrastructure Registry"

Policies to enable API Gateway

The next policy provides necessary access privileges to dynamic group lab-apigw-dynamic-group (and indirectly to the API Gateway dynamically included in that group). This access is limited to lab-compartment (the functions and virtual network in the compartment).

oci iam policy create  --name "dyn-group-gateway-access-lab-compartment" --compartment-id $compartmentId  --statements "[ \"allow dynamic-group lab-apigw-dynamic-group to use virtual-network-family in compartment lab-compartment\",\"allow dynamic-group lab-apigw-dynamic-group to manage public-ips in compartment lab-compartment\",\"allow dynamic-group lab-apigw-dynamic-group to use functions-family in compartment lab-compartment\"]" --description "to allow lab apigw dynamic group access to lab-compartment"

Policies to manage OKE