==== Gitlab and Kubernetes in CIS*3760 F23 ====

This is a guide to assist students in CIS*3760 with the process of deploying an application developed on the SoCS Gitlab Server to our Kubernetes cluster. Each project group will be provided with their own server running RKE2 Kubernetes, on which to deploy. The server will be located at cis3760-XX.socs.uoguelph.ca where XX is your group number.

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

You can interact with Kubernetes in the following ways:

=== Shell into the Server ===

You can ssh directly to your server and run kubectl commands as the root user or using sudo. This is the simplest method of connecting to the server.

=== Install Kubectl on Your Machine ===

If you prefer to interact with Kubernetes directly from your own machine, 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/ |web interface ]], open the hamburger menu at the top left, and select your cluster listed under Explore Cluster. Select Download KubeConfig from the top right menu on this page. The icon looks like a sheet of paper. You can then copy it to your .kube folder which was created in the installation process.

Unfortunately, due to the current lack of VPN access, this method will only work from off campus, or if you proxy your connection through portkey. Directions to do this are beyond the scope of this guide. 

==== Building your Application Container in Gitlab ====

Kaniko is a tool that allows you to build your Docker container automatically as part of a CI/CD Pipeline. 

1. As a prerequisite your Dockerfile containing all of your container build information must be located in the root of your git repository. If you want to place your Dockerfile in a subdirectory you will have to edit the --dockerfile line in the below configuration to specify the new location.

2. Add the following lines to your .gitlab-ci.yml in the root of your Gitlab project repository.

<code>
stages:          # List of stages for jobs, and their order of execution
  - build

build:
  stage: build
  image:
    name: gcr.io/kaniko-project/executor:v1.9.0-debug
    entrypoint: [""]
  script:
    - /kaniko/executor
      --context "${CI_PROJECT_DIR}"
      --dockerfile "${CI_PROJECT_DIR}/Dockerfile"
      --destination "${CI_REGISTRY_IMAGE}:${CI_COMMIT_TAG}"
</code>

Once your container is built it needs to be hosted in a registry to be made available for download. Using the previous configuration file your container is automatically pushed to the Docker Repository integrated into the SoCS Gitlab Server.

==== Integrating Gitlab and Kubernetes with Gitlab Agent ====

Integrate your Gitlab project with the Kubernetes cluster to automatically deploy and update your application as part of the ci/cd pipeline. This section assumes you already follow the previous step and have a project located on the SoCS Gitlab server, and that you have built the project into a Docker container. 

1. Create a file in your Gitlab project at .gitlab/agents/infovis/config.yaml (extension must be yaml, not yml) with the following contents. 

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

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

3. In Gitlab, 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 for use in step 5.

4. In Kubernetes, create two namespaces - one for your project, and the other for the gitlab agent using the following commands.

<code> kubectl create namespace infovis </code>
<code> kubectl create namespace gitlab-agent </code>

5.

Use Helm, a tool for automating kubernetes deployments to install the gitlab agent on your server.

First, copy the contents of the next code block to a file on your kubernetes server named values.yml.

<code>
image:
  repository: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk"
  pullPolicy: IfNotPresent
  # Overrides the image tag whose default is the chart appVersion.
  tag: "v14.8.1"

config:
  kasAddress: 'wss://gitlab.socs.uoguelph.ca:443/-/kubernetes-agent/'
</code>

Next, run the following command on your kubernetes server, specifying your token from step 3, to install the gitlab agent in kubernetes and automatically connect it to your gitlab project. 
<code>helm repo add gitlab https://charts.gitlab.io</code>
<code> helm upgrade --install gitlab-agent gitlab/gitlab-agent --set config.token='TOKEN_FROM_STEP_THREE' --namespace=gitlab-agent -f values.yml </code>

==== Deploying your Application ====

1. Kubernetes needs to be able to connect to the Gitlab Docker Registry. In your Gitlab Project go to Settings > Repository > Deploy Tokens. Enter a name to label the token, a username, and check read_registry

2. Run the following command, substituting the username you entered in the previous step for DOCKER_USER, the token generated for DOCKER_PASSWORD, and an email address of one of the project members for DOCKER_EMAIL. <code> kubectl create secret docker-registry regcred --namespace=infovis --docker-server=registry.socs.uoguelph.ca --docker-username=DOCKER_USER --docker-password=DOCKER_PASSWORD --docker-email=DOCKER_EMAIL </code>

3. A Manifest file needs to be defined in Gitlab. This is a yaml file that lists the kubernetes specifications required to deploy your application within Kubernetes. A sample mainefest file is available in the code block below, and should be placed in manifests/manifest.yml in your Gitlab project repository. The "image:" line will have to be modified with your container URL, and the "host" line will need to be changed to your server URL. The container URL can be found in Gitlab from Packages & Registries > Container Registry.

<code>
apiVersion: apps/v1
kind: Deployment
metadata:
  name: infovis-deployment
  namespace: infovis  # Can be any namespace managed by you that the agent has access to.
spec:
  selector:
    matchLabels:
      app: infovis
  replicas: 1
  template:
    metadata:
      labels:
        app: infovis
    spec:
      containers:
      - name: nginx-custom
        image: registry.socs.uoguelph.ca/cis3760w23/group1/infovis:latest
      imagePullSecrets:
      - name: regcred

---
apiVersion: v1
kind: Service
metadata:
  annotations:
  labels:
    app: infovis
  name: infovis-service
  namespace: infovis
spec:
  ports:
  - name: "80"
    port: 80
    targetPort: 80
  selector:
    app: infovis

---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: infovis-ingress
  namespace: infovis
spec:
  rules:
  - host: cis3760-99.socs.uoguelph.ca
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: infovis-service
            port:
              number: 80
  ingressClassName: nginx
</code>

==== Conclusion ====

All the pieces are now in place to deploy your application automatically to your gitlab server. You can view your application by connecting to your cis3760xx.socs.uoguelph.ca server in a web browser. Each time your container is updated within Gitlab, the agent will automatically pull the latest version to the kubernetes server. 

==== Graphical Representation ====

The following image is a graphical representation of the SoCS Gitlab and Kubernetes Setup and how the pieces fit together and relate to each other.

{{:techsupport:gitlab-k8-agent-schematic.png|}}