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.
- Proceed to the Verify section.
Air Gapped
Use Option 3 on a host inside your fully private VPC.
Overview
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¶
Deploy
rok-tools
in your Kubernetes cluster withkubectl
. Choose one of the following options, based on your cloud provider:$ kubectl apply -f <download_root>/rok-tools-eks.yamlAlternatively, save the
rok-tools-eks
YAML manifest provided below or downloadrok-tools-eks.yaml
and use it locally.Then:
$ kubectl apply -f rok-tools-eks.yamlNote
In case you want to use Docker inside the
rok-tools
environment, e.g., Mirror Images to Internal Registry, use therok-tools-docker-eks.yaml
manifest instead:$ kubectl apply -f <download_root>/rok-tools-docker-eks.yaml$ kubectl apply -f <download_root>/rok-tools-aks.yamlAlternatively, save the
rok-tools-aks
YAML manifest provided below or downloadrok-tools-aks.yaml
and use it locally.Then:
$ kubectl apply -f rok-tools-aks.yamlNote
In case you want to use Docker inside the
rok-tools
environment, e.g., Mirror Images to Internal Registry, use therok-tools-docker-aks.yaml
manifest instead:$ kubectl apply -f <download_root>/rok-tools-docker-aks.yaml$ kubectl apply -f <download_root>/rok-tools-gke.yamlAlternatively, save the
rok-tools-gke
YAML manifest provided below or downloadrok-tools-gke.yaml
and use it locally.Then:
$ kubectl apply -f rok-tools-gke.yamlNote
In case you want to use Docker inside the
rok-tools
environment, e.g., Mirror Images to Internal Registry, use therok-tools-docker-gke.yaml
manifest instead:$ kubectl apply -f <download_root>/rok-tools-docker-gke.yamlVerify 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 20sEnter 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:
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.
See also
Procedure¶
Create your instance based on your cloud provider.
Open the Amazon EC2 console.
From the console dashboard, choose Launch Instance.
Select Amazon Linux 2 AMI (HVM), SSD Volume Type AMI.
Select t2.large or bigger Instance Type.
Click Next: Configure Instance Details.
Specify your network configuration.
- Set Network to your existing VPC.
- Set Subnet to an existing public subnet of your VPC.
- Set Auto-assign Public IP to Use subnet setting (Enable).
Set IAM role to your existing IAM role with elevated privileges.
Click Next: Add Storage.
Increase the size of the Root volume from 8GiB to 100GiB.
Click Next: Add Tags.
Add a tag and set Name and Value to rok-tools.
Click Next: Configure Security Group.
Use a security group that will allow you to have SSH access to the EC2 instance.
Click Review and Launch and then Launch.
Select your existing key pair and click Launch Instances.
This section is a work in progress.
This section is a work in progress.
Connect to your instance based on your cloud provider.
- Open the Amazon EC2 console.
- Locate your instance and click on it.
- Click on Connect.
- Switch to the SSH client tab and follow the instructions.
This section is a work in progress.
This section is a work in progress.
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-userNote
Log out and log back in so that group changes take effect.
This section is a work in progress.
Configure your instance based on your cloud provider.
Increase the PUT response hop limit for
eksctl
to work. To do so:Obtain the region of the instance:
user@bastion:~$ region=$(curl http://169.254.169.254/latest/meta-data/placement/region)Obtain the instance ID of the instance:
user@bastion:~$ instance_id=$(curl http://169.254.169.254/latest/meta-data/instance-id)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.
Specify the
rok-tools
image to use:user@bastion:~$ export IMAGE=gcr.io/arrikto/rok-tools:release-2.0-l0-release-2.0.1Air 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.1(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.
(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"(Optional) Use host networking:
user@bastion:~$ export EXTRA_OPTIONS="--network=host"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: