Create Cloud Identity

Rok requires access to an object storage service to use as its external data store for immutable snapshots of your volumes. This section will guide you through creating an identity that will allow Rok to access the storage service of your cloud provider. You will later enable Rok’s Kubernetes service account to assume it. This approach is considered best practice in all supported platforms.

See also

Choose one of the following options to create the cloud identity:

What You’ll Need

Option 1: Create Cloud Identity Automatically (preferred)

In order to create the cloud identity Rok will use, you will run rok-deploy, which is the standard way to set up Rok on Kubernetes. Rok-deploy is an interactive CLI utility that helps you declaratively configure and deploy a Rok cluster on Kubernetes using GitOps, with minimal effort.

Procedure

Choose one of the following options, based on your cloud provider.

To deploy Rok inside a rok-tools Pod (or Docker container), run:

root@rok-tools:/# rok-deploy

Rok-deploy will prompt you with a graphical interface. Follow the instructions on screen to tailor your installation to your platform, environment, and preferences.

../../_images/rok-deploy.png

Note

rok-deploy will first prompt you to clone Arrikto’s GitOps repository, but you may have already done this in Clone GitOps Repository. In this case, skip this step and proceed to the creation of the IAM resoucres.

Note

Rok-deploy will automatically

  • Discover the OIDC provider of the EKS cluster.
  • Create an IAM role and allow the Kubernetes service account that Rok runs with to assume it without any extra credentials.
  • Create an IAM policy that allows full S3 access for a specific bucket prefix.
  • Attach the IAM policy to the IAM role so that Rok will have access to S3.

Important

The Rok deployment CLI assumes access to both AWS and Kubernetes, e.g., via ~/.kube/config and ~/.aws/{config, credentials} or the environment.

Rok does not currently support the automatic creation of an Azure Managed Identity. Please follow the instructions in the Option 2: Create Cloud Identity Manually section to create an Azure Managed Identity manually.
Rok does not currently support the automatic creation of a Google Workload Identity. Please follow the instructions in the Option 2: Create Cloud Identity Manually section to create a Google Workload Identity manually.

Alternative Procedure

Alternatively, if you didn’t run rok-deploy, use the Arrikto provided script that will automate the process. Choose one of the following options, based on your cloud provider.

Create IAM resources, by running the following command:

root@rok-tools:/# rok-s3-authorize

Important

In case you do not have permissions to create IAM resources, rok-s3-authorize will fail. In this case, run it in dry run mode:

root@rok-tools:/# rok-s3-authorize --dry-run

The CLI tool will prompt you for an output file, where it will output a CloudFormation stack with the required IAM role and policy. You can then send this file to the IAM administrators or, if you are the administrator, you can deploy the stack by following the instructions in the Option 2: Create Cloud Identity Manually section.

You may now proceed to the Verify section.

Rok does not currently support the creation of an Azure Managed Identity via a script. Please follow the instructions in the Option 2: Create Cloud Identity Manually section to create an Azure Managed Identity manually.
Rok does not currently support the creation of a Google Workload Identity via a script. Please follow the instructions in the Option 2: Create Cloud Identity Manually section to create a Google Managed Identity manually.

Option 2: Create Cloud Identity Manually

If you want to create the cloud identity Rok will use manually, follow this section.

Procedure

Choose one of the following options, based on your cloud provider.

Follow these steps to grant a Rok cluster full access to S3 buckets with a specific prefix, i.e., related to an existing EKS cluster.

  1. Set the following environment variables to properly name AWS resources that you will create:

    root@rok-tools:/# export ROK_CLUSTER_NAME=rok
    root@rok-tools:/# export ROK_CLUSTER_NAMESPACE=rok
    root@rok-tools:/# export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query "Account" --output text)
    root@rok-tools:/# export OIDC_PROVIDER=$(aws eks describe-cluster --name $CLUSTERNAME \
    >   --query "cluster.identity.oidc.issuer" \
    >   --output text | sed -e "s/^https:\/\///")
    root@rok-tools:/# STACK_NAME="rok-${AWS_DEFAULT_REGION?}-${CLUSTERNAME?}-${ROK_CLUSTER_NAMESPACE?}-${ROK_CLUSTER_NAME?}"
    root@rok-tools:/# export STACK_NAME=${STACK_NAME%-rok-rok}
    

    Note

    The name of the CloudFormation stack depends on the value of the ROK_CLUSTER_NAME and ROK_CLUSTER_NAMESPACE environment variables. In the majority of the cases these would be rok and rok, respectively, so we prefer to omit the -rok-rok literal from the name of the stack and the IAM resources that will be created.

  2. Go inside your clone of the GitOps repo:

    root@rok-tools:~# cd ~/ops/deployments
    
  3. Format the existing template of the CloudFormation stack with the necessary IAM roles and policies:

    root@rok-tools:~/ops/deployments# j2 rok/eks/s3-iam-resources.yaml.j2 -o s3-iam-resources.yaml
    

    Alternatively, save the s3-iam-resources CloudFormation template provided below or download s3-iam-resources.yaml.j2 and use it locally.

  4. Deploy the CloudFormation stack with:

    root@rok-tools:~/ops/deployments# aws cloudformation deploy --stack-name $STACK_NAME \
    >    --template-file s3-iam-resources.yaml \
    >    --capabilities CAPABILITY_NAMED_IAM
    

Where:

  • stack_name is the name that is associated with the stack.
  • s3-iam-resources.yaml is the file that contains the CloudFormation stack.
  • CAPABILITY_NAMED_IAM specifies that the template is using IAM resources with custom names.

Important

If you don’t have permissions to create IAM resources, share the YAML manifest with your administrator and ask him to deploy the CloudFormation stack with the command above.

To create a Managed Identity on Azure cloud and grant it permissions to access your Azure Storage Account, follow these steps:

  1. Switch to your management environment and retrieve the name of your storage account, as you are going to use it in the following steps:

    root@rok-tools:~# echo ${STORAGE_ACCOUNT_NAME?}
    roka8eb022arriktoarrikto
    
  2. Select the namespace in which to deploy Rok:

    root@rok-tools:/# export ROK_CLUSTER_NAMESPACE=rok
    
  3. Select the name of the Rok cluster:

    root@rok-tools:/# export ROK_CLUSTER_NAME=rok
    
  4. Select the name of the Managed Identity Rok will use to access your storage account:

    root@rok-tools:~# export AZ_MANAGED_IDENTITY=rok-${CLUSTERNAME?}-${ROK_CLUSTER_NAMESPACE?}-${ROK_CLUSTER_NAME?}
    
  5. Remove the Rok cluster namespace and name from the Managed Identity name if they are both equal to rok:

    root@rok-tools:~# export AZ_MANAGED_IDENTITY=${AZ_MANAGED_IDENTITY%-rok-rok}
    
  6. Copy your Managed Identity name to your clipboard as you are going to use this value in the following steps:

    root@rok-tools:~# echo ${AZ_MANAGED_IDENTITY?}
    rok-arrikto-cluster
    
  7. Go to the Managed Identities service in Azure Portal.

  8. Click Create.

  9. On the Basics page, set the following options:

    1. Set Resource group to arrikto so it matches the resource group of your AKS cluster.
    2. Set Region to East US so it matches the region of your AKS cluster.
    3. Set Name to the Managed Identity name you created above.
    ../../_images/managedidentity-create.png
  10. Click Review + create.

  11. Click Create.

  12. Wait for the deployment to complete, and click Go to resource to view the Managed Identity you created.

  13. Click on the Azure role assignments tab.

  14. Click Add role assignment.

  15. Set the following options:

    1. Set Scope to Storage.
    2. Set Subscription to your desired subscription.
    3. Set Resource to the name of the Storage Account you created for Rok.
    4. Set Role to Storage Blob Data Contributor.
    ../../_images/roleassignment-create.png
  16. Click Save.

To create a Workload Identity on Google Cloud and grant it permissions to access Rok’s buckets on Google Cloud Storage, follow these steps:

  1. Select the name of the Google service account for Rok to use:

    root@rok-tools:~# export GCP_SERVICE_ACCOUNT=rok-${CLUSTERNAME?}
    
  2. Create the Google service account:

    root@rok-tools:~# gcloud iam service-accounts create \
    >   --display-name ${GCP_SERVICE_ACCOUNT?} \
    >   ${GCP_SERVICE_ACCOUNT?}
    
  3. Retrieve the email of the service account:

    root@rok-tools:~# export GCP_SERVICE_ACCOUNT_EMAIL=$(\
    >   gcloud iam service-accounts list \
    >   --format "value(email)" \
    >   --filter "displayName:${GCP_SERVICE_ACCOUNT?}")
    
  4. Select the namespace in which to deploy Rok:

    root@rok-tools:~# export ROK_CLUSTER_NAMESPACE=rok
    
  5. Select the name of the Rok cluster:

    root@rok-tools:~# export ROK_CLUSTER_NAME=rok
    
  6. Select the bucket prefix Rok will use to store its snapshots in Google Cloud Storage:

    root@rok-tools:~# export BUCKET_PREFIX=rok-${PROJECT_ID?}-${ZONE?}-${CLUSTERNAME?}-${ROK_CLUSTER_NAMESPACE?}-${ROK_CLUSTER_NAME?}
    
  7. Remove the Rok cluster namespace and name if they are both equal to rok:

    root@rok-tools:~# export BUCKET_PREFIX=${BUCKET_PREFIX%-rok-rok}
    
  8. Select the title for the condition that restricts access to Rok buckets:

    root@rok-tools:~# export TITLE="Only allow access to Rok buckets"
    
  9. Define the expression for the condition to restrict access to Rok buckets:

    root@rok-tools:~# export EXPRESSION="resource.name.startsWith(\"projects/_/buckets/${BUCKET_PREFIX?}\")"
    
  10. Allow the Google service account to access buckets used by Rok in your project on Google Cloud Storage:

    root@rok-tools:~# gcloud projects add-iam-policy-binding \
    >   --member serviceAccount:${GCP_SERVICE_ACCOUNT_EMAIL?} \
    >   --role roles/storage.admin \
    >   --condition "title=${TITLE?},expression=${EXPRESSION?}" \
    >   ${PROJECT_ID?}
    
  11. Enable Rok’s Kubernetes service account to use the Google service account:

    root@rok-tools:~# gcloud iam service-accounts \
    >   add-iam-policy-binding \
    >   --role roles/iam.workloadIdentityUser \
    >   --member "serviceAccount:${PROJECT_ID?}.svc.id.goog[${ROK_CLUSTER_NAMESPACE?}/${ROK_CLUSTER_NAME?}]" \
    >   ${GCP_SERVICE_ACCOUNT_EMAIL?}
    

Verify

Choose one of the following options, based on your cloud provider.

You can view the auto-generated commits that rok-deploy creates in the GitOps repository, under ~/ops/deployments by default. For example:

commit f99e865ede6c677b230d43bf82c25baaca53948e
Author: Rok Deploy v0.15-pre-1303-gab1b01db9 <no-reply@arrikto.com>
Date:   Mon May 25 18:09:06 2020 +0300

   Update Rok manifests

commit bb5e79dc67e1b35a938acfe0d6854a8097e5ec23
Author: Rok Deploy v0.15-pre-1303-gab1b01db9 <no-reply@arrikto.com>
Date:   Mon May 25 18:08:58 2020 +0300

   Update CloudFormation stack to authorize Rok on S3 buckets

You can verify that the Azure Managed Identity exists via the following steps:

  1. Go to the Managed Identities service in Azure Portal. You should be able to see the Managed Identity you created.

    ../../_images/managedidentity-verify.png
  2. Click on the Managed Identity.

  3. Click on Azure role assignments. You should be able to see an assignment with the Storage Blob Data Contributor role and the storage account you created for Rok under the Resource Name.

    ../../_images/roleassignment-verify.png

You can verify that the Google service account exists and has the required privileges via the following steps:

  1. Ensure that Rok’s Kubernetes service account can use the Google service account by verifying that the iam.workloadIdentityUser role is assigned to the service account with the same namespace and name as Rok:

    root@rok-tools:~# gcloud iam service-accounts \
    >   get-iam-policy ${GCP_SERVICE_ACCOUNT_EMAIL?}
    bindings:
    - members:
      - serviceAccount:myproject.svc.id.goog[rok/rok]
      role: roles/iam.workloadIdentityUser
    etag: BwXDFvKhrQM=
    version: 1
    
  2. Ensure that the Google service account can access the buckets used by Rok in your project on Google Cloud Storage by verifying that the storage.admin role is assigned and the condition limits access to buckets whose name starts with rok-<PROJECT_ID>-<ZONE>-<CLUSTERNAME>:

    root@rok-tools:~# gcloud projects get-iam-policy ${PROJECT_ID?} \
    >   --flatten "bindings[].members" \
    >   --filter "bindings.members:serviceAccount:${GCP_SERVICE_ACCOUNT_EMAIL?}"
    ---
    bindings:
      condition:
        expression: resource.name.startsWith("projects/_/buckets/rok-myproject-us-east1-b-arrikto-cluster")
        title: Only allow access to Rok buckets
      members:
    serviceAccount:rok-arrikto-cluster@myproject.iam.gserviceaccount.com
      role: roles/storage.admin
    etag: BwXDowzw1fE=
    version: 3
    

Summary

You have successfully created the cloud identity Rok will use to gain access to your platform’s Object Storage service.

What’s Next

The next step is to authorize Rok to access the Object Storage service using the cloud identity you created.