IBM WebSphere Liberty for Amazon EKS on AWS

Partner Solution Operational Guide

QS

December 2022
Ranjan Kumar, Venu Beyagudem, Paul Baity, Jarek Gawor, Barbara Jones, and Pam Helyar, IBM
Senthil Nagaraj, AWS IBM Alliance team
Troy Lindsay and Vinod Shukla, AWS Integration & Automation team

Visit our GitHub repository to view source files, report bugs, submit feature ideas, and post feedback about this Partner Solution. To comment on the documentation, refer to Feedback.

This Partner Solution was created by IBM in collaboration with Amazon Web Services (AWS). Partner Solutions are automated reference deployments that help people deploy popular technologies on AWS according to AWS best practices. If you’re unfamiliar with AWS Partner Solutions, refer to the AWS Partner Solution General Information Guide.

Overview

This guide covers information you need to use your IBM WebSphere Liberty for Amazon EKS Partner Solution.

For deployment instructions, refer to the IBM WebSphere Liberty for Amazon EKS Partner Solution Deployment Guide.

Connect to the EKS cluster

The steps you follow to connect to the EKS cluster depend on whether you use the boot node. After you connect, you can use kubectl commands to manage your cluster.

Connect with the boot node

  1. In the AWS CloudFormation console, go to the boot node. Look under the Resources tab of the boot-node stack. The node ID is listed in Outputs of the main stack.

  2. Start the boot node.

  3. Enable SSH (Secure Shell) to the boot node. Add a rule to the virtual private cloud (VPC) security group that permits inbound traffic on port 22.

  4. Connect to the boot node by using SSH or EC2 Instance Connect in your browser.

Connect without the boot node

  1. If you haven’t done so already, check your Amazon Resource Name (ARN) configuration. For details, refer to the predeployment steps in the deployment guide.

  2. Use the Kubernetes command line interface to access the EKS cluster.

    1. Run the following command, replacing the information in brackets:

      aws eks update-kubeconfig --name <cluster_name> --region <cluster_region>

      This command updates your kubeconfig file so that you can use kubectl commands to work with your cluster.

    2. Run any kubectl command, such as this one:

      $ kubectl get pods

    3. Confirm that the output messages show a connection to the cluster.

      An Unauthorized error means that your IAM user or role was not granted access to the cluster. To gain access to the cluster, provide your IAM user ARN in the AdditionalEKSAdminArns parameter of the stack.

  3. If needed, ask the creator of the EKS cluster to grant access by adding your IAM user or role to the aws-auth Kubernetes ConfigMap in the kube-system namespace. This ConfigMap maps IAM entities in AWS to user accounts in the Kubernetes cluster. The following steps use eksctl.

    1. Get the ARN of the IAM entity to which you want to grant cluster access.

      • Example user ARN: arn:aws:iam::123456789012:user/user@example.com

      • Example role ARN: arn:aws:iam::123456789012:role/some-role

    2. Run the eksctl command to create a mapping for that IAM entity in the aws-auth ConfigMap.

      eksctl create iamidentitymapping --cluster "<cluster_name>" --region "<cluster_region>" --arn "<arn>"

Find your deployment logs

CloudWatch log streams

You can find Amazon CloudWatch log streams either from the Amazon CloudWatch console or from your AWS CloudFormation stack.

From the CloudWatch console

During or after deployment, and even after a failed deployment, you can view log data in CloudWatch log streams as follows.

  1. Open the CloudWatch console.

  2. In the navigation pane, choose Logs, Log groups.

  3. On the Log groups page, enter the stack name in the search bar.

  4. From the Log streams tab of the log group details, select the log stream to view.

From your CloudFormation stack

After deployment, you can also view log streams from the Outputs tab for your CloudFormation stack.

  1. Choose the Outputs tab for your main stack.

  2. Choose the value of the CloudWatchInstallLogs key.

  3. From the Log streams tab of the log group details, select the output logs.

Lambda function logs

Lambda function logs are at /aws/lambda/ and have the file path /aws/lambda/<name_of_lambda_resource>.

You can view Lambda function logs in CloudWatch.

  1. From the stack Resources tab, select a Lambda function.

  2. Choose the Monitor tab.

  3. Choose View logs in CloudWatch.

Nested stacks such as IBMLibertyBootNodeStack, IBMLibertyEKSClusterStack, and IBMLibertyWorkloadStack have a Lambda function.

SSM logs

SSM logs are on the boot node at /var/log/amazon/ssm/.

Get information about your deployments

To get information about your IBM WebSphere Liberty operator and any applications you’ve deployed, run this command:

$ kubectl get deployments

For a list of namespaces, append -A (shorthand for --all-namespaces). The application name and its namespace depend on your input. If you did not deploy an application, then no application or cert-manager deployments are in your list.

$ kubectl get deployments -A

NAMESPACE    NAME

default      websphereliberty-app-sample
kube-system  coredns
olm          catalog-operator
olm          olm-operator
olm          packageserver
operators    cert-manager
operators    cert-manager-cainjector
operators    cert-manager-webhook
operators    wlo-controller-manager

For stack outputs, go to the Outputs tab for your CloudFormation stack, or go to the CloudWatch console.

The CloudWatch deployment.properties file lists the deployment properties.

Recover from a failed stack

If your stack fails, delete it and retry the deployment. Stack deletion deletes all the artifacts that the stack created, including the EKS cluster and everything deployed in the cluster.

Stack deletion might fail due to timeouts or resource dependencies. If this happens, try to delete the failed stack again. If you installed any external components after the deployment, such as Ingress, those resources are not deleted and might prevent stack deletion. In this case, manually delete the resources that are preventing stack deletion.

Troubleshooting

For troubleshooting common Partner Solution issues, refer to the AWS Partner Solution General Information Guide and Troubleshooting CloudFormation.

Resources

Feedback

To submit feature ideas and report bugs, use the Issues section of the GitHub repository for this Partner Solution. To submit code, refer to the Partner Solution Contributor’s Guide. To submit feedback on this deployment guide, use the following GitHub links:

Notices

This document is provided for informational purposes only. It represents current AWS product offerings and practices as of the date of issue of this document, which are subject to change without notice. Customers are responsible for making their own independent assessment of the information in this document and any use of AWS products or services, each of which is provided "as is" without warranty of any kind, whether expressed or implied. This document does not create any warranties, representations, contractual commitments, conditions, or assurances from AWS, its affiliates, suppliers, or licensors. The responsibilities and liabilities of AWS to its customers are controlled by AWS agreements, and this document is not part of, nor does it modify, any agreement between AWS and its customers.

The software included with this paper is licensed under the Apache License, version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at https://aws.amazon.com/apache2.0/ or in the accompanying "license" file. This code is distributed on an "as is" basis, without warranties or conditions of any kind, either expressed or implied. Refer to the License for specific language governing permissions and limitations.