===== SoCS Kubernetes Cluster =====

**Location:** [[https://kubefarm.socs.uoguelph.ca]]

**Who Has Access:** Faculty or students with faculty, on request

The School of Computer Science has a Kubernetes cluster. It is running the RKE2 Kubernetes distribution, and has [[https://rancher.com/docs/|Rancher]] on top as a management layer and web based graphic interface.

**Important Note:** Due to the design of Kubernetes, it is unaware of Rancher running above it. This means that some things MUST be done through Rancher, while others can be done directly using the Kubernetes command kubectl. This guide will note when something must be done directly via Rancher.

===== How To Interact With Kubernetes ====

You can interact with Kubernetes in the following ways:

=== Directly Through the Web Interface ===

Interacting with Rancher is as simple as logging into Kubefarm and using the interface. To run kubectl commands, from [[ https://kubefarm.socs.uoguelph.ca/c/local/monitoring | cluster manager ]] click on the Launch Kubectl button to bring up a Kubernetes shell. 

=== Install Rancher Command Line Interface ===

Follow the guide from the [[ https://rancher.com/docs/rancher/v2.5/en/cli/ | official Rancher documentation]]. This is the simplest method to connect to Rancher via a command line. To run kubectl commands, preface the command with rancher, ie <code>rancher kubectl get pod</code>

=== Install Kubectl on Your Machine ===

If you prefer to interact with Kubernetes directly, the kubectl command can be installed directly on your local machine. 

Follow the instructions for your Operating system from the [[ https://kubernetes.io/docs/tasks/tools/ | official Kubernetes documentation]].

From the [[ https://kubefarm.socs.uoguelph.ca/c/local/monitoring | Cluster Manager Menu ]], choose Kubeconfig file in the top right of the screen to download this file. You can then copy it to your .kube folder which was created in the installation process.

To access from off campus, ensure you are running the campus VPN and choose Full Tunnel mode. 

==== Gitlab Agent Integration ====

Integrate your Gitlab project with the Kubernetes cluster to automatically deploy and update your project. This Guide assumes you already have a project located in the SoCS Gitlab server, and that you have built the project into a Docker container. 

1. You will need to host your Docker container. If the container can be publicly accessible, this can be hosted in Docker Hub. If it must be private, the SoCS Gitlab installation has it's own Docker Container Registry. To access the SoCS Registry, use ''%% docker login registry.uoguelph.ca %%'' and enter your central login/Gitlab credentials. Directions to tag and push can be found in your Gitlab project under Packages & Registries > Container Registry.

NB: In the future building a Docker container and pushing to the SoCS registry could be done through the CI/CD pipeline, but this is not yet available. 

2. Create .gitlab/agents/agent-name/config.yaml in your Gitlab project, replacing agent-name with whatever you want to name your agent. 

  gitops:
    manifest_projects:
    - id: "Your Project ID"
      paths:
      - glob: '/manifests/*.{yaml,yml,json}'

Replace "Your Project ID" with the ID number of your project. This is listed under the project name in the main project screen.

3. From the Infrastructure > Kubernetes Clusters Menu, choose Add Agent and select the agent named in the previous step. Make sure you save the token that is created.

4. In Kubernetes, create two namespaces One for your project, and the other for the gitlab agent. From the [[ https://kubefarm.socs.uoguelph.ca/c/local/projects-namespaces Projects and Namespaces Menu ]] choose Add Namespace. Enter a name, leaving the other settings at their defaults and choose Create. This step MUST be done through Rancher, otherwise you will not have permissions to access the namespace you create. 

5. <code> kubectl create secret generic -n your-gitlab-agent-namespace gitlab-kubernetes-agent-token --from-literal=token='Your Token Here' </code>

6. Customize the yaml file below with the namespaces you've chosen. You should also ensure the version of the image matches the version gitlab is currently running. 

   TODO
   Put
   Yaml
   Here
   
7. Add the newly created yaml file with kubectl apply -f filename.yml The agent should now be installed. Time to deploy your application.

8. The next two steps are only necessary if you are using the SoCS gitlab server for your container registry, or if you are storing your container in another private registry. In your Gitlab Repo go to Settings > Registry > Deploy Tokens. Enter a name, optionally a username, and check read_registry

9. Run the following command, replacing your credentials. <code>echo -n "{REGISTRY_USERNAME}:{REGISTRY_PASSWORD}" | base64</code>

Replace BASE_64_BASIC_AUTH_CREDENTIALS with the output of the above command. Replace your registry username and password as well.

  {
       "auths": {
           "registry.socs.uoguelph.ca":{
               "username":"REGISTRY_USERNAME",
               "password":"REGISTRY_PASSWORD",
               "email":"REGISTRY_EMAIL",
               "auth":"BASE_64_BASIC_AUTH_CREDENTIALS"
       	   }
       }
   }

Save that file and run <code>cat filename | base64</code> to generate another string. Replace BASE_64_ENCODED_DOCKER_FILE in the below file with that string. Remove any newlines to place the string on one line. Modify the namespace variable with your project namespace.

   apiVersion: v1
   kind: Secret
   metadata:
     name: registry-credentials
     namespace: YOUR NAMESPACE
   type: kubernetes.io/dockerconfigjson
   data:
     .dockerconfigjson: BASE_64_ENCODED_DOCKER_FILE
     
Take this final file, and run <code>kubectl apply -f filename</code>

TODO REPLACE WITH EASIER METHOD kubectl create secret docker-registry <name> --docker-server=DOCKER_REGISTRY_SERVER --docker-username=DOCKER_USER --docker-password=DOCKER_PASSWORD --docker-email=DOCKER_EMAIL

The gitlab agent is now set up and can pull your container from the SoCS container registry.

==== Deploying your Application ====

Look at official documentation TODO add instructions on how to do this. TODO maybe add a sample repository.

The yaml file should be placed in your project git repository.