Create Management Environment

This section will guide you through creating a fully equipped management environment by setting up rok-tools. Rok-tools is a clean Debian environment with all the tools and packages you will need preinstalled.

Choose one of the following options to create your management environment:

• Option 1: If you already have a Kubernetes cluster, follow Option 1: Create Management Environment on Kubernetes (preferred).
• Option 2: If you want to use local Docker, follow Option 2: Create Management Environment on Local Docker.
• Option 3: If you want to use a Cloud instance, follow Option 3: Create Management Environment on a Cloud Instance.

Fast Forward

If you have already created your management environment, expand this box to fast-forward.

1. Proceed to the Verify section.

Air Gapped

Use Option 3 on a host inside your fully private VPC.

Option 1: Create Management Environment on Kubernetes (preferred)

This section will guide you through creating a management environment on Kubernetes. Rok-tools runs as a StatefulSet in the default namespace and uses the default storage class for the PVC, where it persists its data.

What You’ll Need

• A Kubernetes cluster that you can access with kubectl from your machine.

Important

By applying the following YAML manifest you enable rok-tools to run with cluster-admin privileges. You will need this only if you plan to deploy Rok on the same Kubernetes cluster with rok-tools.

If you plan to deploy Rok on a different Kubernetes cluster (see Create Kubernetes Cluster) rok-tools does not require cluster admin privileges.

Procedure

1. Deploy rok-tools in your Kubernetes cluster with kubectl. Choose one of the following options, based on your cloud provider:

   AWS

   Azure

   Google Cloud

   

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

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

   + show: rok-tools-eks.yaml

   # This file is part of Rok. # # Copyright © 2020-2022 Arrikto Inc. All Rights Reserved. apiVersion: v1 kind: ServiceAccount metadata: name: rok-tools labels: app: rok-tools --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: rok-tools-cluster-admin subjects: - kind: ServiceAccount name: rok-tools namespace: default roleRef: kind: ClusterRole name: cluster-admin apiGroup: rbac.authorization.k8s.io --- apiVersion: v1 kind: Service metadata: name: rok-tools spec: selector: app: rok-tools ports: - protocol: TCP port: 80 targetPort: 80 name: http - protocol: TCP port: 8080 targetPort: 8080 name: port-forward --- apiVersion: apps/v1 kind: StatefulSet metadata: name: rok-tools labels: app: rok-tools spec: replicas: 1 serviceName: rok-tools selector: matchLabels: app: rok-tools template: metadata: labels: app: rok-tools spec: # hostPID: true serviceAccountName: rok-tools containers: - name: rok-tools image: gcr.io/arrikto/rok-tools:release-2.0-l0-release-2.0.2 imagePullPolicy: IfNotPresent workingDir: /root ports: - containerPort: 80 - containerPort: 8080 volumeMounts: - name: data mountPath: /root # securityContext: # privileged: true volumeClaimTemplates: - metadata: name: data spec: accessModes: ["ReadWriteOnce"] resources: requests: storage: 50Gi storageClassName: gp2

   Then:

   

   $ kubectl apply -f rok-tools-eks.yaml

   Note

   In case you want to use Docker inside the rok-tools environment, e.g., Mirror Images to Internal Registry, use the rok-tools-docker-eks.yaml manifest instead:

   

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

   

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

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

   + show: rok-tools-aks.yaml

   # This file is part of Rok. # # Copyright © 2020-2022 Arrikto Inc. All Rights Reserved. apiVersion: v1 kind: ServiceAccount metadata: name: rok-tools labels: app: rok-tools --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: rok-tools-cluster-admin subjects: - kind: ServiceAccount name: rok-tools namespace: default roleRef: kind: ClusterRole name: cluster-admin apiGroup: rbac.authorization.k8s.io --- apiVersion: v1 kind: Service metadata: name: rok-tools spec: selector: app: rok-tools ports: - protocol: TCP port: 80 targetPort: 80 name: http - protocol: TCP port: 8080 targetPort: 8080 name: port-forward --- apiVersion: apps/v1 kind: StatefulSet metadata: name: rok-tools labels: app: rok-tools spec: replicas: 1 serviceName: rok-tools selector: matchLabels: app: rok-tools template: metadata: labels: app: rok-tools spec: # hostPID: true serviceAccountName: rok-tools containers: - name: rok-tools image: gcr.io/arrikto/rok-tools:release-2.0-l0-release-2.0.2 imagePullPolicy: IfNotPresent workingDir: /root ports: - containerPort: 80 - containerPort: 8080 volumeMounts: - name: data mountPath: /root # securityContext: # privileged: true volumeClaimTemplates: - metadata: name: data spec: accessModes: ["ReadWriteOnce"] resources: requests: storage: 50Gi storageClassName: default

   Then:

   

   $ kubectl apply -f rok-tools-aks.yaml

   Note

   In case you want to use Docker inside the rok-tools environment, e.g., Mirror Images to Internal Registry, use the rok-tools-docker-aks.yaml manifest instead:

   

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

   

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

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

   + show: rok-tools-gke.yaml

   # This file is part of Rok. # # Copyright © 2020-2022 Arrikto Inc. All Rights Reserved. apiVersion: v1 kind: ServiceAccount metadata: name: rok-tools labels: app: rok-tools --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: rok-tools-cluster-admin subjects: - kind: ServiceAccount name: rok-tools namespace: default roleRef: kind: ClusterRole name: cluster-admin apiGroup: rbac.authorization.k8s.io --- apiVersion: v1 kind: Service metadata: name: rok-tools spec: selector: app: rok-tools ports: - protocol: TCP port: 80 targetPort: 80 name: http - protocol: TCP port: 8080 targetPort: 8080 name: port-forward --- apiVersion: apps/v1 kind: StatefulSet metadata: name: rok-tools labels: app: rok-tools spec: replicas: 1 serviceName: rok-tools selector: matchLabels: app: rok-tools template: metadata: labels: app: rok-tools spec: # hostPID: true serviceAccountName: rok-tools containers: - name: rok-tools image: gcr.io/arrikto/rok-tools:release-2.0-l0-release-2.0.2 imagePullPolicy: IfNotPresent workingDir: /root ports: - containerPort: 80 - containerPort: 8080 volumeMounts: - name: data mountPath: /root # securityContext: # privileged: true volumeClaimTemplates: - metadata: name: data spec: accessModes: ["ReadWriteOnce"] resources: requests: storage: 50Gi storageClassName: standard

   Then:

   

   $ kubectl apply -f rok-tools-gke.yaml

   Note

   In case you want to use Docker inside the rok-tools environment, e.g., Mirror Images to Internal Registry, use the rok-tools-docker-gke.yaml manifest instead:

   

   $ kubectl apply -f <download_root>/rok-tools-docker-gke.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 the container:

   

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

You can now proceed to the Verify section.

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.

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 Kubernetes services.

What You’ll Need

• Docker on your machine.

Procedure

Start the rok-tools container locally with Docker:

$ 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-2.0-l0-release-2.0.2

You can now proceed to the Verify section.

Option 3: Create Management Environment on a Cloud Instance

What You’ll Need

Here is what you’ll need based on your cloud provider.

AWS

Azure

Google Cloud

• Access to the AWS Management Console.
• An existing IAM role and instance profile with elevated privileges.
• An existing VPC.
• An existing public subnet with auto-assign public IP address attribute enabled.
• An existing SSH key pair.

See also

• Get started guide for EC2 instances

This section is a work in progress.

This section is a work in progress.

Procedure

1. Create your instance based on your cloud provider.

   AWS

   Azure

   Google Cloud

   1. Open the Amazon EC2 console.

   2. From the console dashboard, choose Launch Instance.

   3. Select Amazon Linux 2 AMI (HVM), SSD Volume Type AMI.

   4. Select t2.large or bigger Instance Type.

   5. Click Next: Configure Instance Details.

   6. Specify your network configuration.

      1. Set Network to your existing VPC.
      2. Set Subnet to an existing public subnet of your VPC.
      3. Set Auto-assign Public IP to Use subnet setting (Enable).
      

   7. Set IAM role to your existing IAM role with elevated privileges.

   8. Click Next: Add Storage.

   9. Increase the size of the Root volume from 8GiB to 100GiB.

   10. Click Next: Add Tags.

   11. Add a tag and set Name and Value to rok-tools.

   12. Click Next: Configure Security Group.

   13. Use a security group that will allow you to have SSH access to the EC2 instance.

   14. Click Review and Launch and then Launch.

   15. Select your existing key pair and click Launch Instances.

   This section is a work in progress.

   This section is a work in progress.

2. Connect to your instance based on your cloud provider.

   AWS

   Azure

   Google Cloud

   1. Open the Amazon EC2 console.
   2. Locate your instance and click on it.
   3. Click on Connect.
   4. Switch to the SSH client tab and follow the instructions.

   This section is a work in progress.

   This section is a work in progress.

3. Inside your instance, install Docker based on your OS.

   Amazon Linux 2

   Ubuntu

   

   user@bastion:~$ sudo yum install -y docker user@bastion:~$ sudo systemctl start docker user@bastion:~$ sudo systemctl enable docker user@bastion:~$ sudo usermod -a -G docker ec2-user

   Note

   Log out and log back in so that group changes take effect.

   This section is a work in progress.

4. Configure your instance based on your cloud provider.

   AWS

   Azure

   Google Cloud

   Increase the PUT response hop limit for eksctl to work. To do so:

   1. Obtain the region of the instance:

      

      user@bastion:~$ region=$(curl http://169.254.169.254/latest/meta-data/placement/region)

   2. Obtain the instance ID of the instance:

      

      user@bastion:~$ instance_id=$(curl http://169.254.169.254/latest/meta-data/instance-id)

   3. Modify instance metadata options to increase the HTTP PUT response hop limit for instance metadata requests:

      

      user@bastion:~$ aws ec2 modify-instance-metadata-options \ > --region $region \ > --instance-id $instance_id \ > --http-put-response-hop-limit 2 \ > --http-endpoint enabled

   This section is a work in progress.

   This section is a work in progress.

5. Specify the rok-tools image to use:

   

   user@bastion:~$ export IMAGE=gcr.io/arrikto/rok-tools:release-2.0-l0-release-2.0.2

   Air Gapped

   Use the mirrored rok-tools image from your internal registry. For example:

   

   user@bastion:~$ export IMAGE=${INTERNAL_REGISTRY?}/gcr.io/arrikto/rok-tools:release-2.0-l0-release-2.0.2

6. (Optional) Specify the trusted CA bundle you want to use. Assuming your host is properly configured, bind mount the system wide trusted CA bundle inside rok-tools based on your OS.

   Amazon Linux 2

   Ubuntu

   

   user@bastion:~$ export EXTRA_VOLUME="-v /etc/ssl/certs/ca-bundle.crt:/etc/ssl/certs/ca-certicates.crt:ro"

   This section is a work in progress.

7. (Optional) Configure AWS SDK inside rok-tools to use your trusted CA bundle:

   

   user@bastion:~$ export EXTRA_ENV="-e AWS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt"

8. (Optional) Use host networking:

   

   user@bastion:~$ export EXTRA_OPTIONS="--network=host"

9. Start the rok-tools container using Docker:

   

   user@bastion:~$ 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 \ > ${EXTRA_VOLUME} \ > ${EXTRA_ENV} \ > ${EXTRA_OPTIONS} \ > ${IMAGE?}

Verify

Ensure the latest version of rok-deploy is available:

root@rok-tools:~# rok-deploy --version Rok rok-deploy Build ID Rok 2.0.2 "Aurora" (release - release-2.0) (iliastsi@rok-dev) (GCC 6.3.0) 2023-03-31T13:49:56Z

Summary

You have successfully created a fully equipped management environment to deploy and manage Rok on Kubernetes using GitOps.

What’s Next

The next step is to configure Git in your management environment.

• Configure Git