Chapter 18. Deploying an application

1. A Provisioned ROSA cluster

   This lab assumes you have access to a successfully provisioned a ROSA cluster. If you have not yet created a ROSA cluster, see ROSA quick start guide for more information.

2. The OpenShift Command Line Interface (CLI)

   For more information, see Getting started with the OpenShift CLI.

3. A GitHub Account

   Use your existing GitHub account or register at https://github.com/signup.

1. Split your desktop screen between the OpenShift web console and the OSToy application web console so that you can see the results of your actions immediately.

   

   If you cannot split your screen, open the OSToy application web console in another tab so you can quickly switch to the OpenShift web console after activating the features in the application.

2. From the OpenShift web console, select Workloads > Deployments > ostoy-frontend to view the OSToy deployment.

   

1. From the OSToy application web console, click Home in the left menu, and enter a message in the Crash Pod box, for example, This is goodbye!.

2. Click Crash Pod.

   

   The pod crashes and Kubernetes should restart the pod.

   

1. From the OpenShift web console, quickly switch to the Deployments screen. You will see that the pod turns yellow, meaning it is down. It should quickly revive and turn blue. The revival process happens quickly so you might miss it.

   

Verification

1. From the web console, click Pods > ostoy-frontend-xxxxxxx-xxxx to change to the pods screen.

   

2. Click the Events sub-tab and verify that the container crashed and restarted.

   

Procedure

1. In the OSToy application, click Networking in the left menu.

2. Review the networking configuration. The right tile titled "Hostname Lookup" illustrates how the service name created for a pod can be used to translate into an internal ClusterIP address.

   

3. Enter the name of the microservice created in the right tile ("Hostname Lookup") following the format of <service_name>.<namespace>.svc.cluster.local. You can find this service name in the service definition of ostoy-microservice.yaml by running the following command:

   $ oc get service <name_of_service> -o yaml

   Example output

   apiVersion: v1
   kind: Service
   metadata:
     name: ostoy-microservice-svc
     labels:
       app: ostoy-microservice
   spec:
     type: ClusterIP
     ports:
       - port: 8080
         targetPort: 8080
         protocol: TCP
     selector:
       app: ostoy-microservice

   In this example, the full hostname is ostoy-microservice-svc.ostoy.svc.cluster.local.

4. You see an IP address returned. In this example it is 172.30.165.246. This is the intra-cluster IP address, which is only accessible from within the cluster.

   

1. Run the following script to configure your ROSA cluster to forward logs to CloudWatch:

   $ curl https://raw.githubusercontent.com/openshift-cs/rosaworkshop/master/rosa-workshop/ostoy/resources/configure-cloudwatch.sh | bash

   Note

   Configuring ROSA to send logs to CloudWatch goes beyond the scope of this tutorial. Integrating with AWS and enabling CloudWatch logging are important aspects of ROSA, so a script is included to simplify the configuration process. The script will automatically set up AWS CloudWatch. You can examine the script to understand the steps involved.

   Example output

   Varaibles are set...ok.
   Policy already exists...ok.
   Created RosaCloudWatch-mycluster role.
   Attached role policy.
   Deploying the Red Hat OpenShift Logging Operator
   namespace/openshift-logging configured
   operatorgroup.operators.coreos.com/cluster-logging created
   subscription.operators.coreos.com/cluster-logging created
   Waiting for Red Hat OpenShift Logging Operator deployment to complete...
   Red Hat OpenShift Logging Operator deployed.
   secret/cloudwatch-credentials created
   clusterlogforwarder.logging.openshift.io/instance created
   clusterlogging.logging.openshift.io/instance created
   Complete.

2. After a few minutes, you should begin to see log groups inside of AWS CloudWatch. Run the following command to see the log groups:

   $ aws logs describe-log-groups --log-group-name-prefix rosa-mycluster

   Example output

   {
       "logGroups": [
           {
               "logGroupName": "rosa-mycluster.application",
               "creationTime": 1724104537717,
               "metricFilterCount": 0,
               "arn": "arn:aws:logs:us-west-2:000000000000:log-group:rosa-mycluster.application:*",
               "storedBytes": 0,
               "logGroupClass": "STANDARD",
               "logGroupArn": "arn:aws:logs:us-west-2:000000000000:log-group:rosa-mycluster.application"
           },
           {
               "logGroupName": "rosa-mycluster.audit",
               "creationTime": 1724104152968,
               "metricFilterCount": 0,
               "arn": "arn:aws:logs:us-west-2:000000000000:log-group:rosa-mycluster.audit:*",
               "storedBytes": 0,
               "logGroupClass": "STANDARD",
               "logGroupArn": "arn:aws:logs:us-west-2:000000000000:log-group:rosa-mycluster.audit"
           },

1. Output a message to stdout.

   1. In the OSToy application, click Home and then click the message box for Log Message (stdout).
   2. Write a message to output to the stdout stream, for example "All is well!".

   3. Click Send Message.

      

2. Output a message to stderr.

   1. Click the message box for Log Message (stderr).
   2. Write a message to output to the stderr stream, for example "Oh no! Error!".

   3. Click Send Message.

      

1. Enter the following command in the command line interface (CLI) to retrieve the name of your frontend pod:

   $ oc get pods -o name

   Example output

   pod/ostoy-frontend-679cb85695-5cn7x 1
   pod/ostoy-microservice-86b4c6f559-p594d

   1

   The pod name is ostoy-frontend-679cb85695-5cn7x.

2. Run the following command to see both the stdout and stderr messages:

   $ oc logs <pod-name>

   Example output

   $ oc logs ostoy-frontend-679cb85695-5cn7x
   [...]
   ostoy-frontend-679cb85695-5cn7x: server starting on port 8080
   Redirecting to /home
   stdout: All is well!
   stderr: Oh no! Error!

1. Navigate to CloudWatch on the AWS web console.

2. In the left menu, click Logs and then Log groups to see the different groups of logs. You should see 3 groups:

   • rosa-<cluster-name>.application
   • rosa-<cluster-name>.audit

   • rosa-<cluster-name>.infrastructure

     

3. Click rosa-<cluster-name>.application.

4. Click the log stream for the frontend pod.

   

5. Filter for stdout and stderr.

6. Expand the row to show the messages you entered earlier and other pertinent information.

   

7. Return to the log streams and select the microservice.
8. Enter "microservice" in the search bar to see other messages in your logs.

9. Expand one of the entries to see the color the frontend pod received from microservice and which pod sent that color to the frontend pod.

   

1. You have created a ROSA cluster.

2. Retrieve your login command

   1. If you are not logged in via the CLI, in OpenShift Cluster Manager, click the dropdown arrow next to your name in the upper-right and select Copy Login Command.

      
   2. A new tab opens. Enter your username and password, and select the authentication method.
   3. Click Display Token
   4. Copy the command under "Log in with this token".

   5. Log in to the command line interface (CLI) by running the copied command in your terminal. You should see something similar to the following:

      $ oc login --token=RYhFlXXXXXXXXXXXX --server=https://api.osd4-demo.abc1.p1.openshiftapps.com:6443

      Example output

      Logged into "https://api.myrosacluster.abcd.p1.openshiftapps.com:6443" as "rosa-user" using the token provided.
      
      You don't have any projects. You can try to create a new project, by running
      
      oc new-project <project name>

3. Create a new project from the CLI by running the following command:

   $ oc new-project ostoy-s2i

1. Add secret to OpenShift

   The example emulates a .env file and shows how easy it is to move these directly into an OpenShift environment. Files can even be renamed in the Secret. In your CLI enter the following command, replacing <UserName> with your GitHub username:

   $ oc create -f https://raw.githubusercontent.com/<UserName>/ostoy/master/deployment/yaml/secret.yaml

2. Add ConfigMap to OpenShift

   The example emulates an HAProxy config file, and is typically used for overriding default configurations in an OpenShift application. Files can even be renamed in the ConfigMap.

   In your CLI enter the following command, replacing <UserName> with your GitHub username:

   $ oc create -f https://raw.githubusercontent.com/<UserName>/ostoy/master/deployment/yaml/configmap.yaml

3. Deploy the microservice

   You must deploy the microservice first to ensure that the SERVICE environment variables are available from the UI application. --context-dir is used here to only build the application defined in the microservice directory in the git repository. Using the app label allows us to ensure the UI application and microservice are both grouped in the OpenShift UI. Run the following command in the CLI to create the microservice, replacing <UserName> with your GitHub username:

   $ oc new-app https://github.com/<UserName>/ostoy \
       --context-dir=microservice \
       --name=ostoy-microservice \
       --labels=app=ostoy

   Example output

   --> Creating resources with label app=ostoy ...
       imagestream.image.openshift.io "ostoy-microservice" created
       buildconfig.build.openshift.io "ostoy-microservice" created
       deployment.apps "ostoy-microservice" created
       service "ostoy-microservice" created
   --> Success
       Build scheduled, use 'oc logs -f buildconfig/ostoy-microservice' to track its progress.
       Application is not exposed. You can expose services to the outside world by executing one or more of the commands below:
        'oc expose service/ostoy-microservice'
       Run 'oc status' to view your app.

4. Check the status of the microservice

   Before moving onto the next step we should be sure that the microservice was created and is running correctly by running the following command:

   $ oc status

   Example output

   In project ostoy-s2i on server https://api.myrosacluster.g14t.p1.openshiftapps.com:6443
   
   svc/ostoy-microservice - 172.30.47.74:8080
     dc/ostoy-microservice deploys istag/ostoy-microservice:latest <-
       bc/ostoy-microservice source builds https://github.com/UserName/ostoy on openshift/nodejs:14-ubi8
       deployment #1 deployed 34 seconds ago - 1 pod

   Wait until you see that it was successfully deployed. You can also check this through the web UI.

5. Deploy the front end UI

   The application has been designed to rely on several environment variables to define external settings. Attach the previously created Secret and ConfigMap afterward, along with creating a PersistentVolume. Enter the following into the CLI:

   $ oc new-app https://github.com/<UserName>/ostoy \
       --env=MICROSERVICE_NAME=OSTOY_MICROSERVICE

   Example output

   --> Creating resources ...
       imagestream.image.openshift.io "ostoy" created
       buildconfig.build.openshift.io "ostoy" created
       deployment.apps "ostoy" created
       service "ostoy" created
   --> Success
       Build scheduled, use 'oc logs -f buildconfig/ostoy' to track its progress.
       Application is not exposed. You can expose services to the outside world by executing one or more of the commands below:
        'oc expose service/ostoy'
       Run 'oc status' to view your app.

6. Update the Deployment

   Update the deployment to use a "Recreate" deployment strategy (as opposed to the default of RollingUpdate) for consistent deployments with persistent volumes. Reasoning here is that the PV is backed by EBS and as such only supports the RWO method. If the deployment is updated without all existing pods being killed it might not be able to schedule a new pod and create a PVC for the PV as it’s still bound to the existing pod. If you will be using EFS you do not have to change this.

   $ oc patch deployment ostoy --type=json -p \
       '[{"op": "replace", "path": "/spec/strategy/type", "value": "Recreate"}, {"op": "remove", "path": "/spec/strategy/rollingUpdate"}]'

7. Set a Liveness probe

   Create a Liveness Probe on the Deployment to ensure the pod is restarted if something isn’t healthy within the application. Enter the following into the CLI:

   $ oc set probe deployment ostoy --liveness --get-url=http://:8080/health

8. Attach Secret, ConfigMap, and PersistentVolume to Deployment

   Run the following commands attach your secret, ConfigMap, and PersistentVolume:

   1. Attach Secret

      $ oc set volume deployment ostoy --add \
          --secret-name=ostoy-secret \
          --mount-path=/var/secret

   2. Attach ConfigMap

      $ oc set volume deployment ostoy --add \
          --configmap-name=ostoy-config \
          -m /var/config

   3. Create and attach PersistentVolume

      $ oc set volume deployment ostoy --add \
          --type=pvc \
          --claim-size=1G \
          -m /var/demo_files

9. Expose the UI application as an OpenShift Route

   Run the following command to deploy this as an HTTPS application that uses the included TLS wildcard certificates:

   $ oc create route edge --service=ostoy --insecure-policy=Redirect

10. Browse to your application with the following methods:

    • Running the following command opens a web browser with your OSToy application:

      $ python -m webbrowser "$(oc get route ostoy -o template --template='https://{{.spec.host}}')"

    • You can get the route for the application and copy and paste the route into your browser by running the following command:

      $ oc get route

1. Log in to the cluster console.
2. On the left menu, click Operators, then OperatorHub.

3. In the filter box, enter "S3" and select AWS Controller for Kubernetes - Amazon S3.

   

4. If a pop-up about community operators appears, click Continue.
5. Click Install.
6. Select All namespaces on the cluster under "Installation mode".
7. Select ack-system under "Installed Namespace".

8. Select Manual under "Update approval".

   Important

   Make sure Manual Mode is selected so changes to the service account are not overwritten by an automatic operator update.

9. Click Install.

   The settings should look like the below image.

   

10. Click Approve.
11. The installation begins but will not complete until you have created an IAM role and policy for the ACK controller.

1. Run one of the following scripts to create the AWS IAM role for the ACK controller and assign the S3 policy:

   • Automatically download the setup-s3-ack-controller.sh script, which automates the process for you.

   • Run the following script in your command line interface (CLI):

     $ curl https://raw.githubusercontent.com/openshift-cs/rosaworkshop/master/rosa-workshop/ostoy/resources/setup-s3-ack-controller.sh | bash

2. When the script completes, it restarts the deployment which updates the service controller pods with the IAM roles for service accounts environment variables.

3. Confirm that the environment variables are set by running the following command:

   $ oc describe pod ack-s3-controller -n ack-system | grep "^\s*AWS_"

   Example output

   AWS_ROLE_ARN:                 arn:aws:iam::000000000000:role/ack-s3-controller
   AWS_WEB_IDENTITY_TOKEN_FILE:  /var/run/secrets/eks.amazonaws.com/serviceaccount/token

4. Confirm successful setup of the ACK controller in the web console by clicking Operators and then Installed operators.

   

5. If you do not see a successful Operator installation and the environment variables, manually restart the deployment by running the following command:

   $ oc rollout restart deployment ack-s3-controller -n ack-system

1. Create a new unique project for OSToy by running the following command:

   $ oc new-project ostoy-$(uuidgen | cut -d - -f 2 | tr '[:upper:]' '[:lower:]')

2. Save the name of the namespace and project to an environment variable by running the following command:

   $ export OSTOY_NAMESPACE=$(oc config view --minify -o 'jsonpath={..namespace}')

1. Get your AWS account ID by running the following command:

   $ export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

2. Get the OIDC provider by running the following command, replacing <cluster-name> with the name of your cluster:

   $ export OIDC_PROVIDER=$(rosa describe cluster -c <cluster-name> -o yaml | awk '/oidc_endpoint_url/ {print $2}' | cut -d '/' -f 3,4)

3. Create the trust policy file by running the following command:

   $ cat <<EOF > ./ostoy-sa-trust.json
   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "Federated": "arn:aws:iam::${AWS_ACCOUNT_ID}:oidc-provider/${OIDC_PROVIDER}"
         },
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Condition": {
           "StringEquals": {
             "${OIDC_PROVIDER}:sub": "system:serviceaccount:${OSTOY_NAMESPACE}:ostoy-sa"
           }
         }
       }
     ]
   }
   EOF

4. Create the AWS IAM role to be used with your service account by running the following command:

   $ aws iam create-role --role-name "ostoy-sa-role" --assume-role-policy-document file://ostoy-sa-trust.json

1. Get the S3 full access policy ARN by running the following command:

   $ export POLICY_ARN=$(aws iam list-policies --query 'Policies[?PolicyName==`AmazonS3FullAccess`].Arn' --output text)

2. Attach the policy to the AWS IAM role by running the following command:

   $ aws iam attach-role-policy --role-name "ostoy-sa-role" --policy-arn "${POLICY_ARN}"

1. Get the ARN for the AWS IAM role we created so that it will be included as an annotation when you create your service account by running the following command:

   $ export APP_IAM_ROLE_ARN=$(aws iam get-role --role-name=ostoy-sa-role --query Role.Arn --output text)

2. Create the service account by running the following command:

   $ cat <<EOF | oc apply -f -
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: ostoy-sa
     namespace: ${OSTOY_NAMESPACE}
     annotations:
       eks.amazonaws.com/role-arn: "$APP_IAM_ROLE_ARN"
   EOF

   Important

   Do not change the name of the service account from "ostoy-sa" or you will have to change the trust relationship for the AWS IAM role.

3. Grant the service account the restricted role by running the following command:

   $ oc adm policy add-scc-to-user restricted system:serviceaccount:${OSTOY_NAMESPACE}:ostoy-sa

4. Confirm that the annotation was successful by running the following command:

   $ oc describe serviceaccount ostoy-sa -n ${OSTOY_NAMESPACE}

   Example output

   Name:                ostoy-sa
   Namespace:           ostoy
   Labels:              <none>
   Annotations:         eks.amazonaws.com/role-arn: arn:aws:iam::000000000000:role/ostoy-sa-role
   Image pull secrets:  ostoy-sa-dockercfg-b2l94
   Mountable secrets:   ostoy-sa-dockercfg-b2l94
   Tokens:              ostoy-sa-token-jlc6d
   Events:              <none>

1. Create an S3 bucket using a manifest file by running the following command:

   $ cat <<EOF | oc apply -f -
   apiVersion: s3.services.k8s.aws/v1alpha1
   kind: Bucket
   metadata:
     name: ${OSTOY_NAMESPACE}-bucket
     namespace: ${OSTOY_NAMESPACE}
   spec:
     name: ${OSTOY_NAMESPACE}-bucket
   EOF

   Important

   The OSToy application expects to find a bucket named <namespace>-bucket. If you use anything other than the namespace of your OSToy project, this feature will not work. For example, if our project is "ostoy", the value for name must be ostoy-bucket.

2. Confirm the bucket was created by running the following command:

   $ aws s3 ls | grep ${OSTOY_NAMESPACE}-bucket

1. Run your pod with the service account you created.

2. Deploy the microservice by running the following command:

   $ - oc apply -f https://raw.githubusercontent.com/openshift-cs/rosaworkshop/master/rosa-workshop/ostoy/yaml/ostoy-microservice-deployment.yaml

3. Deploy the ostoy-frontend by running the following command:

   $ - oc apply -f https://raw.githubusercontent.com/openshift-cs/rosaworkshop/master/rosa-workshop/ostoy/yaml/ostoy-frontend-deployment.yaml

4. Patch the ostoy-frontend deployment by running the following command:

   $ oc patch deploy ostoy-frontend -n ${OSTOY_NAMESPACE} --type=merge --patch '{"spec": {"template": {"spec":{"serviceAccount":"ostoy-sa"}}}}'

   Example output

   spec:
     # Uncomment to use with ACK portion of the workshop
     # If you chose a different service account name please replace it.
     serviceAccount: ostoy-sa
     containers:
     - name: ostoy-frontend
       image: quay.io/ostoylab/ostoy-frontend:1.6.0
       imagePullPolicy: IfNotPresent
   [...]

5. Wait for the pod to update.

1. Get the route for the newly deployed application by running the following command:

   $ oc get route ostoy-route -n ${OSTOY_NAMESPACE} -o jsonpath='{.spec.host}{"\n"}'

2. Open a new browser tab and enter the route obtained in the previous step.

   Important

   Be sure to use http:// and not https://.

3. Click ACK S3 in the left menu in OSToy.

4. Because it is a new bucket, the bucket should be empty.

   

1. Click ACK S3 in the left menu in OSToy.
2. Scroll down to Upload a text file to S3.
3. Enter a file name for your file.
4. Enter content for your file.

5. Click Create file.

   

6. Scroll to the top section for existing files and confirm that the file you just created is there.

7. Click the file name to view the file.

   

8. Confirm with the AWS CLI by running the following command to list the contents of your bucket:

   $ aws s3 ls s3://${OSTOY_NAMESPACE}-bucket

   Example output

   $ aws s3 ls s3://ostoy-bucket
   2023-05-04 22:20:51         51 OSToy.txt