Skip to main content

Getting Started

Prerequisites​

To install and set up the Kube OBLV Stack chart, there are a few important configuration steps that need to be completed. These steps involve configuring the necessary dependencies for three controllers that are required for proper functionality. Once these configurations are in place, you can proceed with the installation process.

Users guide

This page content is for administrators who want to deploy an application with OBLV Deploy. If you are a user and want to connect to a deployed application, refer to the Making an Attested Connection guide.

The kube-oblv-stack is a Helm chart designed for Kubernetes deployment. It includes the OBLV Deploy Helm chart, which creates Nitro Enclave clusters, as well as the required dependencies. Each dependency below is a controller that needs its own configuration. You need to create the service account and link their IAM Policy to it:

  • Amazon Controller for Kubernetes (ACK): The ACK is a tool that lets you directly manage AWS services from Kubernetes. ACK lets you provision and manage EC2 instances to run Nitro Enclaves using the Kubernetes API.
  • EKS Load Balancer Plugin: The LoadBalancer Controller is a controller that manages Elastic Load Balancers (ELBs) for a cluster. It's designed to work with Amazon EKS (Elastic Kubernetes Service) and provides a way to expose the applications running inside the enclaves to users through AWS Load Balancers.
  • Bitnami External DNS Chart: The Bitnami External DNS Addon is a Kubernetes add-on that automatically manages DNS records for services in a Kubernetes cluster. It sets up DNS records pointing towards LoadBalancers so that the users can connect to the applications using the DNS name.

The Kube OBLV Stack chart can be installed with all the bundled dependencies, or you can choose to install only the required ones if they have already been installed in the cluster.

How to choose dependencies

When installing oblv-deploy-stack umbrella chart, you should set the enabled value to true for controllers or subcharts that you want to install. For example, if the AWS Load balancer controller is not already installed, you would set the enabled=true value:

  --set aws-load-balancer-controller.enabled=false

Prerequisites for KMS Integration​

  1. Create the required IAM role which allows EC2 to talk to S3 and KMS
aws iam create-role \
    --role-name EC2_S3_KMS_Role \
    --assume-role-policy-document '{
        "Version": "2012-10-17",
        "Statement": [{
            "Effect": "Allow",
            "Principal": {
                "Service": "ec2.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }]
    }' \
    --description "IAM role for EC2 instances with S3 and KMS access"

# Attach policies to the role
aws iam attach-role-policy \
    --role-name EC2_S3_KMS_Role \
    --policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess

aws iam attach-role-policy \
    --role-name EC2_S3_KMS_Role \
    --policy-arn arn:aws:iam::aws:policy/AWSKeyManagementServicePowerUser
  1. Create a policy document called key_policy.json file which allows decryption from enclave.
{
  "Version": "2012-10-17",
  "Id": "key-default-1",
  "Statement": [
			  {
            "Sid": "Enable decrypt from enclave",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<ACCOUNT_ID>:role/EC2_S3_KMS_Role"
            },
            "Action": "kms:Decrypt",
            "Resource": "*",
            "Condition": {
              "StringEqualsIgnoreCase": {
                  "kms:RecipientAttestation:ImageSha384": "<PCR0>"
              }
          }
      },
      {
          "Sid": "Allow access for Key Administrators",
          "Effect": "Allow",
          "Principal": {
              "AWS": "arn:aws:iam::<ACCOUNT_ID>:user/<ADMIN_ROLE_NAME>"
          },
          "Action": [
              "kms:Create*",
              "kms:Describe*",
              "kms:Enable*",
              "kms:List*",
              "kms:Put*",
              "kms:Update*",
              "kms:Revoke*",
              "kms:Disable*",
              "kms:Get*",
              "kms:Delete*",
              "kms:TagResource",
              "kms:UntagResource",
              "kms:ScheduleKeyDeletion",
              "kms:CancelKeyDeletion"
          ],
          "Resource": "*"
      }
  ]
}
  1. Create the key using policy document from the previous step and note the ARN of the key
aws kms create-key --description "Nitro Enclaves Key" \
	--policy file://key_policy.json \
	--query KeyMetadata.Arn --output text
  1. Now, create a CA certificate key pair and store it in S3. We will store the public certificate in S3 and encrypt the private key with the KMS key created above and store it in the S3 as well
openssl genrsa -out $(pwd)/ca.key 2048

openssl req -x509 -new -nodes \
	 -key $(pwd)/ssl/ca.key -sha256 \
	 -days 3650 -out $(pwd)/ca.crt \
	 -subj "/C=/ST=/L=/O=/OU=/CN="
	
aws kms encrypt \
	--key-id $kms_key --plaintext \
	fileb://$(pwd)/ca.key \
	--query CiphertextBlob --output text > $(pwd)/encrypted_ca.key

aws s3 cp $(pwd)/ca.crt s3://<BUCKETNAME>/ca.crt
aws s3 cp $(pwd)/encrypted_ca.key s3://<BUCKETNAME>/encrypted_ca.key

Prerequisites for ACK EC2 Chart​

Controllers require permissions to manage AWS resources from within the Kubernetes Cluster. This is made possible with the help of Kubernetes Service Accounts that are attached to IAM Policies that defines the required permissions. The role of the ACK controller is to spin up EC2's and attach an IAM Instance profile to it that is required for the integration with KMS within the enclave.

For spinning up the EC2's, the controller will use the arn:aws:iam::aws:policy/AmazonEC2FullAccess policy, but we will also need to allow the controller to pass in the Instance Profile to the EC2 and AWS Nitro Enclave instances.

  1. Create an IAM policy document named ack_chart_passrole_iam_policy.json that allows the controller to pass in the Instance profile:
  {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Effect": "Allow",
              "Action": "iam:PassRole",
              "Resource": "<ARN of the instance profile role>",
              "Condition": {
                  "StringEquals": {
                      "iam:PassedToService": [
                          "ec2.amazonaws.com",
                          "enclave.amazonaws.com"
                      ]
                  }
              }
          }
      ]
  }
  1. Use the policy document to create an IAM Policy:
  aws iam create-policy \
    --policy-name "ACKPassRolePolicy" \
    --policy-document file://ack_chart_passrole_iam_policy.json
Important

Remember to copy the Amazon Resource Names (ARN) of the IAM Policy object returned by this command. The ARN will be used in the next step.

  1. Create a service account for the ACK EC2 controller and attach the required policies to it, run:
  eksctl create iamserviceaccount \
    --cluster=${CLUSTER_NAME} \
    --namespace=kube-system \
    --name=ack-ec2-controller \
    --role-name=AmazonACKec2ControllerRole \
    --attach-policy-arn=arn:aws:iam::aws:policy/AmazonEC2FullAccess \
    --attach-policy-arn={ARN of the created IAM Policy from the previous step}\
    --override-existing-serviceaccounts \
    --region ${CLUSTER_REGION} \
    --approve
Reference

You can find more information about this command on the ACK EC2 Chart reference page.

Prerequisites for the LoadBalancer Controller​

The AWS LoadBalancer Controller spins up load balancers to expose applications running inside the enclaves for its users. The policy document required for the AWS LoadBalancer controller can be downloaded.

  1. Download the policy document:
  curl -O https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.5.4/docs/install/iam_policy.json
  1. Using the downloaded policy document, create the IAM Policy for the LoadBalancer Controller:
  aws iam create-policy \
    --policy-name AWSLoadBalancerControllerIAMPolicy \
    --policy-document file://iam_policy.json
Important

Remember to copy the Amazon Resource Names (ARN) of the IAM Policy object returned by this command. The ARN will be used in the next step.

  1. Create a service account for the AWS LoadBalancer Controller and attach the policy to it:
  eksctl create iamserviceaccount \
    --cluster=${CLUSTER_NAME} \
    --namespace=kube-system \
    --name=aws-load-balancer-controller \
    --role-name AmazonEKSLoadBalancerControllerRole \
    --attach-policy-arn={ARN of the created IAM Policy from the previous step} \
    --region ${CLUSTER_REGION} \
    --approve
Reference

You can find more information about these commands in the LoadBalancer Controller reference page.

Prerequisites for the External DNS Addon​

The External DNS controller creates DNS records pointing at the Load Balancers, so that users can just use the hostname while connecting to the applications hosted inside the enclaves.

For the External DNS controller to work, it requires permissions to list and change Route53 resources inorder to sync the DNS records as and when needed.

  1. Create a policy document named external_dns_iam_policy.json:
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "route53:ChangeResourceRecordSets"
        ],
        "Resource": [
          "arn:aws:route53:::hostedzone/${HOSTED_ZONE_ID}"
        ]
      },
      {
        "Effect": "Allow",
        "Action": [
          "route53:ListHostedZones",
          "route53:ListResourceRecordSets"
        ],
        "Resource": [
          "*"
        ]
      }
    ]
  }
  1. Using the created policy document, create an IAM Policy for the DNS Controller.
  aws iam create-policy \
  --policy-name "ExternalDNSUpdatesPolicy" \
  --policy-document file://external_dns_iam_policy.json
Important

Remember to copy the Amazon Resource Names (ARN) of the IAM Policy object returned by this command. The ARN will be used in the next step.

  1. Create a Service Account for the External DNS Controller and attach the IAM Policy to it.
  eksctl create iamserviceaccount \
    --name external-dns \
    --namespace kube-system \
    --cluster ${CLUSTER_NAME} \
    --attach-policy-arn={ARN of the created IAM Policy from the previous step} \
    --approve \
    --override-existing-serviceaccounts \
    --region ${CLUSTER_REGION}
Reference

You can find more information about these commands in the External DNS Addon reference page.

What's Next?​

After installing everything OBLV Deploy needs to run, you can access the Installation and Setup page to continue with the Getting Started guide.