Prepare Management Environment

To run this guide you need a management environment. This will be the environment from which you will run all the commands mentioned in this guide.

Important

This does not have to be the same environment where Rok will eventually run. You will use this environment for management and configuration purposes only.

You first need to create your management environment, then configure it, and finally verify it works properly.

Create management environment

Please choose one of the following options to create your management environment.

Option 1: Create management environment on Kubernetes (preferred)

If you already have a K8s cluster and can access it with kubectl from your machine you can easily create a fully equipped deployment environment by installing rok-tools. Rok-tools runs as a StatefulSet and is the standard utility that provides a clean Debian environment with all needed tools and packages pre-installed. It lives in the default namespace and uses the default storage class for the PVC where it persists its data.

Important

By applying the following YAML manifest you enable rok-tools to run with cluster-admin privileges. This is needed only if you plan to deploy Rok on the same K8s cluster with rok-tools.

If you plan to deploy Rok on a different K8s cluster (see Provision EKS cluster) rok-tools does not require cluster admin privileges.

  1. Deploy rok-tools in your K8s cluster with kubectl:

    $ kubectl apply -f <download_root>/rok-tools.yaml
    

    Alternatively, save the rok-tools YAML manifest provided below or download rok-tools.yaml and use it locally.

    Then simply:

    $ kubectl apply -f rok-tools.yaml
    

    Note

    In case you want to use Docker inside the rok-tools environment, e.g., Mirror images to private registry, use the rok-tools-docker.yaml manifest instead:

    $ kubectl apply -f <download_root>/rok-tools-docker.yaml
    
  2. Verify that the rok-tools Pod is ready:

    $ kubectl get pods rok-tools-0
    NAME          READY   STATUS    RESTARTS   AGE
    rok-tools-0   1/1     Running   0          20s
    
  3. Enter its container with:

    $ kubectl exec -ti statefulset/rok-tools -- /bin/bash
    

You may now continue with the Configure your management environment section to see how to set up needed tools in the bootstrapped environment.

Option 2: Create management environment on local Docker

If you don’t have access to a Kubernetes cluster, you can use Docker to start a rok-tools container locally on your machine. This will automatically provide a clean Debian environment with all needed tools and packages pre-installed.

Note

To ensure your data is persistent, start the rok-tools container with a volume attached to it. Moreover, map TCP port 8080 of the container to port 8080 on the Docker host, so that you can later expose K8s services.

To start the rok-tools container locally with Docker run:

$ mkdir rok-tools-data
$ docker run -ti \
>     --name rok-tools \
>     --hostname rok-tools \
>     -p 8080:8080 \
>     --entrypoint /bin/bash \
>     -v $(pwd)/rok-tools-data:/root \
>     -v /var/run/docker.sock:/var/run/docker.sock \
>     -w /root \
>     gcr.io/arrikto/rok-tools:release-1.1-l0-release-1.1-rc5

Configure your management environment

Once you have successfully created a deployment environment as described in the Create management environment section, you need to perform some manual configuration in it.

Before you proceed, exec into the rok-tools container:

For Kubernetes:

$ kubectl exec -ti statefulset/rok-tools /bin/bash

For Docker:

$ docker exec -ti rok-tools /bin/bash

Configure Git

To configure Git please follow the next steps.

Deployment Key

To deploy Rok on Kubernetes you will need to set up git with a deployment key for the https://github.com/arrikto/deployments GitOps repository.

Important

If you don’t already have a deployment key please coordinate with Arrikto’s Tech Team to set up one for you.

Rok-tools is configured to perform strict host checking and uses the key found in /root/.ssh/id_rsa in order to establish an SSH connection to github.com. For this, you need to:

  1. Create the SSH configuration directory for user root:

    root@rok-tools-0:/# mkdir /root/.ssh
    
  2. Get key from github.com and generate its fingerprint:

    root@rok-tools-0:/# ssh-keyscan github.com >> github_key
    root@rok-tools-0:/# ssh-keygen -lf github_key
    
  3. Cross-check the generated fingerprint with the official GitHub fingerprints

  4. Update known_hosts:

    root@rok-tools-0:/# cat github_key >> /root/.ssh/known_hosts
    root@rok-tools-0:/# rm github_key
    
  5. Decrypt the Arrikto provided private SSH key:

    1. Open a terminal and run:

      root@rok-tools-0:/# gpg -d > /root/.ssh/id_rsa
      

      The command will appear to hang while it is waiting for the encrypted text.

    2. Copy the encrypted text from the email, including the -----BEGIN PGP MESSAGE----- and -----END PGP MESSAGE----- lines

    3. Paste the encrypted text into the terminal, including the -----BEGIN PGP MESSAGE----- and -----END PGP MESSAGE----- lines

    4. gpg will prompt you for the passphrase

    5. Enter the passphrase

    6. Press ctrl-d to signal to gpg that there is no more input

    7. You should end up with the private SSH key in /root/.ssh/id_rsa

  6. Set the correct permissions for the file:

    root@rok-tools-0:/# chmod 400 /root/.ssh/id_rsa
    
  7. Verify that you can connect to github.com with SSH:

    root@rok-tools-0:/# ssh -T git@github.com
    

Identity

Git needs a username and e-mail when it performs commits. To set this information globally run:

$ git config --global user.name "John Doe"
$ git config --global user.email johndoe@example.com

Configure AWS

This section assumes that you already have an AWS account and an associated IAM user with Administrator privileges. To access AWS from inside the deployment environment we will use the Access key ID and Secret Access Key for this IAM user.

Note

If you have already configured the aws CLI for your IAM user, you can skip to the next section.

To configure the aws CLI we follow the official Amazon docs.

Here we will create and configure the default AWS profile. During the setup, you will be prompted for your AWS credentials and desired default region:

root@rok-tools-0:/# aws configure
AWS Access Key ID [None]: *****************XYZ
AWS Secret Access Key [None]: *****************xyz
Default region name [None]: us-east-1
Default output format [None]:

Note

In case you have already AWS CLI configured somewhere, e.g., with multiple profiles, role profiles, etc., you can simply copy ~/.aws/config and ~/.aws/credentials into the rok-tools container. If you are not going to use the default profile, make sure you set AWS_PROFILE accordingly.

Configure access to Arrikto’s Private Registry

Arrikto distributes container images via a private Container Registry on Google Cloud (gcr.io).

In order for Kubernetes to successfully pull the images of Rok components from this container registry you need to obtain a Docker JSON configuration file that contains a key with proper rights and has the following format:

{
      "auths": {
               "gcr.io": {
                        "auth": "<BASE_64_STRING>"
               }
      }
}

Important

If you don’t already have a Docker configuration file, please coordinate with Arrikto’s Tech Team to set up one for you.

For more information on this mechanism read the official Kubernetes docs on imagePullSecrets.

During the deployment process, the Rok provisioning tool (rok-deploy) will ask for the location of this Docker JSON and then commit it in the GitOps repository under the manifests tree. For this, you will need to make it available inside rok-tools.

Exec inside the rok-tools container and decrypt the Arrikto provided Docker config:

  1. Open a terminal and run:

    root@rok-tools-0:/# gpg -d > /root/dockerconfig.json
    

    The command will appear to hang while it is waiting for the encrypted text.

  2. Copy the encrypted text from the email, including the -----BEGIN PGP MESSAGE----- and -----END PGP MESSAGE----- lines

  3. Paste the encrypted text into the terminal, including the -----BEGIN PGP MESSAGE----- and -----END PGP MESSAGE----- lines

  4. gpg will prompt you for the passphrase

  5. Enter the passphrase

  6. Press ctrl-d to signal to gpg that there is no more input

  7. You should end up with the deployments key in /root/dockerconfig.json

Caution

This will save your key unencrypted in /root/dockerconfig.json

Configure environment variables

In subsequent sections, this guide uses the AWS_ACCOUNT, AWS_IAM_USER and AWS_DEFAULT_REGION environment variables to generate names for resources to be created. Thus, you need to set them in advance.

For example:

root@rok-tools-0:/# export AWS_ACCOUNT=arrikto
root@rok-tools-0:/# export AWS_IAM_USER=username

Note

Make sure you properly set the above environment variables with your own AWS account and IAM username.

In case you have a custom AWS configuration and you don’t want to use the default profile, make sure to also export the AWS_PROFILE environment variable accordingly (see also the official AWS CLI guide on environment variables).

Assuming that you have already specified the default region for your profile in your AWS CLI configuration, retrieve it and export it as an environment variable as well:

root@rok-tools-0:/# export AWS_DEFAULT_REGION=$(aws configure get region)

Verify your management environment

  1. Verify aws is available:

    root@rok-tools-0:/# aws --version
    aws-cli/2.0.4 Python/3.7.3 Linux/4.15.0-34-generic botocore/2.0.0dev8
    
  2. Ensure aws is correctly configured:

    root@rok-tools-0:/# aws sts get-caller-identity
    root@rok-tools-0:/# aws iam list-access-keys
    
  3. Verify eksctl is available:

    root@rok-tools-0:/# eksctl version
    0.16.0
    
  4. Verify kubectl is available:

    root@rok-tools-0:/# kubectl version
    Client Version: version.Info{Major:"1", Minor:"16", GitVersion:"v1.16.9", GitCommit:"a17149e1a189050796ced469dbd78d380f2ed5ef", GitTreeState:"clean", BuildDate:"2020-04-16T11:44:51Z", GoVersion:"go1.13.9", Compiler:"gc", Platform:"linux/amd64"}
    
  5. Verify istioctl is available:

    root@rok-tools-0:/# istioctl version --remote=false
    1.5.7