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: 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:

    $ 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.

    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.

    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.

    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-1.3-l0-release-1.3-rc8

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.

  • 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.
This section is a work in progress.
This section is a work in progress.

Procedure

  1. Create your instance based on your cloud provider.

    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).
      ../../_images/ec2-launch-network.png
    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.

    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.

    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.

    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-1.3-l0-release-1.3-rc8
    
  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.

    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 1.3-rc8 "Sapphire" (release - release-1.3) (iliastsi@rok-dev) (GCC 6.3.0) 2021-08-26T12:54:01Z

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.