Tutorial: Adding a database instance to an AWS EKS cluster, using the Db2 Operator

1. From a web browser, go to https://portal.aws.amazon.com/billing/signup .
2. Follow the online instructions.
   NOTE: You will be contacted by phone and be required to enter a verification code on you phone keypad.

You use the eksctl utility to create an Amazon EKS cluster for your Db2® deployment. You can also use the utility to define the node type properties for your cluster.

Shared file storage is the best option for your database metadata and backups. To make use of shared file storage, you create an Amazon Elastic File System (EFS) storage class for your EKS cluster. Creating shared file storage involves the following steps:

• Creating a role and attaching a policy for setting up EFS.
• Installing the AWS EFS CSI Driver, using a manifest.
• Creating an AWS EFS File System for your EKS cluster.
• Creating a storage class for your EFS file system.

Procedure

1. Create a role and attach a policy for configuring the EFS CSI driver.
   1. Download the IAM policy:

      curl -o iam-policy-example.json https://raw.githubusercontent.com/kubernetes-sigs/aws-efs-csi-driver/v1.3.7/docs/iam-policy-example.json

   2. Install the IAM Policy:

      aws iam create-policy --policy-name AmazonEKS_EFS_CSI_Driver_Policy --policy-document file://iam-policy-example.json

   3. Create the IAM role and attach the IAM policy to the role:

      eksctl create iamserviceaccount --cluster ${CLUSTER} --namespace kube-system --name efs-csi-controller-sa --attach-policy-arn arn:aws:iam::${ACCOUNT_ID}:policy/AmazonEKS_EFS_CSI_Driver_Policy --approve --region ${REGION}

      where
      • cluster is the name of your EKS cluster.
      • namespace is the Kubernetes namespace that you want to associate with the role.
      • name is the name you want to assign to the role.
      • region is where your AWS instance is being deployed.
2. Install the AWS EFS CSI Driver, using a manifest.
   To run applications on an Amazon EKS cluster that is configured for shared file storage (EFS), you need to create and mount an EFS file system on your cluster. To mount the file system, you need to download and install the Amazon EFS Container Storage Interface (CSI) driver.
   1. Download the manifest:

      kubectl kustomize "github.com/kubernetes-sigs/aws-efs-csi-driver/deploy/kubernetes/overlays/stable/?ref=release-1.3" > public-ecr-driver.yaml 

   2. Edit the public-ecr-driver.yaml file to remove the efs-csi-controller-sa ServiceAccount. This service account was created previously.
   3. Install the CSI driver:

      kubectl apply -f public-ecr-driver.yaml

      This command also creates pods in the kube-system namespace.
   4. Check that the pods are created in the namespace:

      kubectl get pods -n kube-system

3. Create an AWS EFS File System for your EKS cluster.
   1. Retrieve the virtual private cloud (VPC) ID of your EKS cluster:

      vpc_id=$(aws eks describe-cluster --name ${CLUSTER} --query "cluster.resourcesVpcConfig.vpcId" --output text)

   2. Retrieve the subnetting (CIDR) range for the cluster's VPC:

      cidr_range=$(aws ec2 describe-vpcs --vpc-ids ${vpc_id} --query "Vpcs[].CidrBlock" --output text)

   3. Create a security group using the vpc_id:

      security_group_id=$(aws ec2 create-security-group --group-name ${EFS_SG} --description "My EFS security group" --vpc-id $vpc_id --output text)
   4. Create an inbound rule that allows inbound nfs traffic from the CIDR for your cluster's vpc:

      aws ec2 authorize-security-group-ingress --group-id $security_group_id --protocol tcp --port 2049 --cidr $cidr_range

   5. Create an AWS EFS file system for your EKS cluster in the same region as your EKS cluster:

      file_system_id=$(aws efs create-file-system --region ${REGION} --performance-mode generalPurpose --query 'FileSystemId' --output text)

   6. Create the mount targets:
      1. Determine the subnet IDs in your VPC of your EKS cluster:

         TAG="tag:alpha.eksctl.io/cluster-name"
         eks_subnet_ids=$(aws ec2 describe-subnets --filters "Name=vpc-id,Values=${vpc_id}" "Name=${TAG},Values=${CLUSTER}" --query 'Subnets[*].SubnetId' --output text)

      2. Run the following code to create your mount targets for each of the subnets in your EKS Cluster:

         for subnet in ${eks_subnet_ids}; do
             aws efs create-mount-target --file-system-id ${file_system_id} --security-groups ${security_group_id} --subnet-id ${subnet}
         done

4. Create a storage class for your EFS file system.
   Ensure that you have the following information before running the command to create your EFS storage class:
   • provisioningMode: The EFS access point mode. Use efs-ap.
   • fileSystemId: The EFS file system ID. For example, - fs-08a5b4467d198bf3e.
   • uid: The access point user ID. Use zero (0).
   • gid: The access point group ID. Use zero (0).
   • directoryPerms: The directory permissions for the access point root directory. Use 777.
   Run the following command to create the storage class for your EFS file system. Include the ID of the AWS EFS File System that you created for your EKS cluster:

   cat << EOF | kubectl create -f -
   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   metadata:
     name: efs-test-sc
   parameters:
     directoryPerms: "777"
     fileSystemId: ${file_system_id}
     gid: "0"
     provisioningMode: efs-ap
     uid: "0"
   provisioner: efs.csi.aws.com
   reclaimPolicy: Delete
   volumeBindingMode: Immediate
   EOF

Procedure

1. Log in to your Amazon EKS cluster.
2. Install the ibm-db2uoperator-catalog in the namespace where olm is installed:

   cat << EOF | kubectl create -f -
   apiVersion: operators.coreos.com/v1alpha1
   kind: CatalogSource
   metadata:
     name: ibm-db2uoperator-catalog
     namespace: olm
   spec:
     displayName: IBM Db2U Catalog
     image: icr.io/cpopen/ibm-db2uoperator-catalog@sha256:13d8219d19d6980224200699c4c423332e64de5644b5e5564389012e1a3ff9c1
     publisher: IBM
     sourceType: grpc
     updateStrategy:
       registryPoll:
         interval: 45m
   EOF

3. Create a namespace for installing the Db2 operator:
   kubectl create namespace ${NAMESPACE}
4. Install an operator group in the namespace:

   cat << EOF | kubectl create -f -
   apiVersion: operators.coreos.com/v1
   kind: OperatorGroup
   metadata:
     name: db2u-operator-group
     namespace: ${NAMESPACE}
   spec:
     targetNamespaces:
     - ${NAMESPACE}
   EOF

5. Create a subscription in the namespace to deploy the Db2 operator:

   cat << EOF | kubectl create -f -
   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: ibm-db2uoperator-catalog-subscription
     namespace: ${NAMESPACE}
     generation: 1
   spec:
     channel: v110509.0
     name: db2u-operator
     installPlanApproval: Automatic
     source: ibm-db2uoperator-catalog
     sourceNamespace: olm
     startingCSV: db2u-operator.v110509.0.1
   EOF

6. Check that the db2u-operator pod is deployed:

   kubectl get pods -n ${NAMESPACE} | grep db2u-operator

7. After the db2u-operator pod is up and running, run the YAML code to deploy your database instance.
   Choose from the following:
   • YAML for the Db2 instance.
   • YAML for the single-partition Db2 Warehouse instance.
   • YAML for the multi-partition Db2 Warehouse instance.
8. Check the status of your Db2uInstance:

   kubectl get db2uinstance -n ${NAMESPACE} ${DB2U_INSTANCE_NAME}

   where DB2U_INSTANCE_NAME is the name value set in the metadata section of the YAML code. For example,

   name: db2oltp-test

9. When the STATE value returned is Ready, the instance is deployed successfully.

   ${DB2U_INSTANCE_NAME}
   NAME                        STATE   MAINTENANCESTATE          AGE
   db2oltp-test          Ready         None               6h8m

10. Log on to the database engine pod as db2inst1:

    kubectl -n ${NAMESPACE} exec -it $(oc get pods -n ${NAMESPACE} | grep ${DB2U_INSTANCE_NAME}-db2u-0 | awk '{print $1}') -- su - db2inst1

11. Connect to the database bludb on your AWS cluster:

    db2 connect to bludb

Connect to a Db2 database from outside the EKS cluster

• Install the AWS Load Balancer Controller add-on.
• Tag the public and private subnets in the Virtual Private Cloud (VPC) that is being used by your EKS cluster.
• Create an External Load Balancer service.

1. Install the AWS Load Balancer Controller add-on.
2. Tag the private subnets and public subnets in the Virtual Private Cloud (VPC) that is used by your EKS cluster:
   1. Get the vpc_id of your cluster:

      vpc_id=$(aws eks describe-cluster --name ${CLUSTER} --query "cluster.resourcesVpcConfig.vpcId" --output text)

   2. Find the public subnets of your VPC:

      public_subnets=$(aws ec2 describe-subnets --filter Name=vpc-id,Values=$vpc_id --query 'Subnets[?MapPublicIpOnLaunch==`true`].SubnetId')

   3. Find the private subnets of your VPC:

      private_subnets=$(aws ec2 describe-subnets --filter Name=vpc-id,Values=$vpc_id --query 'Subnets[?MapPublicIpOnLaunch==`false`].SubnetId')

   4. Tag the public subnets:

      for subnet_id in "${public_subnets[@]}"; do
          aws ec2 create-tags --resources "$subnet_id" --tags Key=kubernetes.io/role/elb,Value=1 Key=kubernetes.io/cluster/${CLUSTER},Value=owned
      done

   5. Tag the private subnets:

      for subnet_id in "${private_subnets[@]}"; do
          aws ec2 create-tags --resources "$subnet_id" --tags Key=kubernetes.io/role/internal-elb,Value=1
      done
3. Create an External Load Balancer service.
   To expose the TCP/IP listener port of your Db2 deployment, you need to log in to your deployed EKS cluster and create a Load Balancer service.
   1.  Create a Load Balancer service. Define the variable LOAD_BALANCER_SVC and name it (e.g., db2u-db2wh-load-balancer)
      The following example shows the command syntax for exposing both the Transport Layer Security (TLS/SSL) port number (50001) and the non-TLS/SSL Db2 port number (50000) for a Db2 Warehouse deployment:

      kubectl create -f - << EOF 
      ---
      apiVersion: v1
      kind: Service
      metadata:
        annotations:
          service.beta.kubernetes.io/aws-load-balancer-attributes: load_balancing.cross_zone.enabled=true
          service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: instance
          service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
          service.beta.kubernetes.io/aws-load-balancer-target-node-labels: topology.kubernetes.io/zone=${REGION}
          service.beta.kubernetes.io/aws-load-balancer-type: external
        name: ${LOAD_BALANCER_SVC} 
        namespace: ${NAMESPACE}
      spec:
        allocateLoadBalancerNodePorts: true
        internalTrafficPolicy: Cluster
        externalTrafficPolicy: Cluster
        ipFamilies:
        - IPv4
        ipFamilyPolicy: SingleStack
        ports:
        - name: legacy-server
          port: 50000
        - name: ssl-server
          port: 50001
        publishNotReadyAddresses: true
        selector:
          app: ${DB2U_DEPLOYMENT_NAME}
          component: db2wh
          formation_id: ${DB2U_DEPLOYMENT_NAME}
          role: db
          type: engine
        type: LoadBalancer
      EOF

      Once the the Load Balancer service is created, EKS creates a public (external) IP address and exposes the target port that is defined in the service specification.
      Note: It takes about 5 minutes for the service to be provisioned and exposed on external traffic.
   2. Query your EKS cluster for the Load Balancer service to get the public IP address:

      kubectl get svc -n ${NAMESPACE} | grep ${LOAD_BALANCER_SVC} 
      db2u-db2wh-load-balancer   LoadBalancer   10.0.247.179  k8s-db2u-cdb2ueks-774f18ba0e-659d91e7552f2355.elb.us-east-2.amazonaws.com 50001:32331/TCP,50000:31831/TCP   14d 
   3. Test whether the Load Balancer service endpoint is accessible from outside the EKS cluster by using a curl command.
      The following example shows the command syntax for testing the accessibility of the service endpoint 3.23.82.224 on port 50000:

      curl -kv k8s-db2u-cdb2ueks-774f18ba0e-659d91e7552f2355.elb.us-east-2.amazonaws.com:50000
      *   Trying 3.23.82.224:50000...
      * Connected to k8s-db2u-cdb2ueks-774f18ba0e-659d91e7552f2355.elb.us-east-2.amazonaws.com (3.23.82.224) port 50000 (#0)
      > GET / HTTP/1.1
      > Host: k8s-db2u-cdb2ueks-774f18ba0e-659d91e7552f2355.elb.us-east-2.amazonaws.com:50000
      > User-Agent: curl/8.1.2
      > Accept: */*
      >