Testing the Prometheus integration with the GitLab Development Kit requires some additional components. This is because the Prometheus integration requires a CI/CD deploy on Kubernetes.
Testing the Prometheus integration with the GitLab Development Kit requires some
additional components. This is because the Prometheus integration requires a
CI/CD deploy on Kubernetes.
Because of this, you will need to either run a local Kubernetes cluster or use a service like the Google Container Engine (GKE).
Because of this, you will need to either run a local Kubernetes cluster or use
a service like the Google Container Engine (GKE).
Setting it up locally with [Minikube](https://github.com/kubernetes/minikube) is often easier, as you do not have to worry about Runners in GKE requiring network access to your local GDK instance.
Setting it up locally with [Minikube](https://github.com/kubernetes/minikube)
is often easier, as you do not have to worry about Runners in GKE requiring
network access to your local GDK instance.
## Instructions for Minikube on OS X
## Instructions for Minikube
The following steps will help you set up Mnikube locally.
### Install kubectl if you do not have it
Kubectl is required for Minikube to function. You will need to download it, and add it to your path.
Displays the URL to access the newly started Prometheus server. Browse to it to ensure it is operational.
The following command will display the URL to access the newly started Prometheus
server. Browse to it to ensure it is operational:
```
minikube service --url prometheus
```
### Configure GDK to listen to more than localhost.
## Configure GDK to listen to more than localhost.
From the GDK root directory, create a host file to configure GDK to listen for more than just localhost. This will allow the Runner to connect to your GDK instance.
From the GDK root directory, create a host file to configure GDK to listen for
more than just localhost. This will allow the Runner to connect to your GDK instance:
```
echo 0.0.0.0 > host
```
### Edit `gitlab.yml` to configure GDK to use your real IP not localhost.
## Edit GitLab's `gitlab.yml`
We need to configure GDK to inform it of the real IP address of your computer.
This is because GDK returns this information to the Runner, and if it is wrong,
pipelines will fail.
1. Get your local IP address by running `ifconfig` or opening up Network Settings
if on macOS. On Linux you can also use `ip addr show`.
1. Open `gitlab/config/gitlab.yml` and change the `host: localhost` line to
reflect the IP of the previous step.
1. Save the file and restart GDK to apply this change.
We need to configure GDK to inform it of the real IP address of your computer. This is because GDK returns this information to the Runner, and if it is wrong, Pipelines will fail. You can get your IP address by running `ifconfig` or opening up Network Settings.
You should now be able to access GitLab by the external URL
(e.g., `http://192.168.1.1` not `localhost`), otherwise it may not work correctly.
Open `gitlab/config/gitlab.yml` and change the `host: localhost` line to reflect your IP.
## Create a Project
Once saved, restart GDK to apply this change.
Now that we have GDK running, we need to go and create a project with CI/CD
set up. The easiest way to do this, is to simply import from an existing project
with a simplified `gitlab-ci.yml`.
> Note: you should now access GitLab by the external URL (e.g. http://192.168.1.1 not localhost), otherwise it may not work correctly.
Import https://gitlab.com/joshlambert/hello-world.git, to use a very simple
CI/CD pipeline with no requirements (it just spins up a hello-world container).
### Create a Project
## Edit the Runner's configMap yaml file
Now that we have GDK running, we need to go and create a project with CI/CD set up. The easiest way to do this, is to simply import from an existing project with a simplified `gitlab-ci.yml`.
This file configures the Runner to talk to GDK, and we need to edit two sections
of this file.
Import `https://gitlab.com/joshlambert/hello-world.git`, to use a very simple CI/CD pipeline with no requirements. (It just spins up a hello-world container.)
First, we need to replace the existing IP with your computer’s real IP address.
1. Replace the existing IP with your local IP address that you found when you
configured `gitlab.yml`.
1. Replace the registration token with the Runner's token of your project. Find
it under **Project ➔ Settings ➔ CI/CD Pipelines ➔ Runner token**.
Next, replace the registration token with the token for your project.
>**Note:**
If your project's token contains uppercase characters, it will fail
due to a bug in the Runner. You can manually set the token further down
the CI/CD settings screen. Set it to all lowercase letters and numbers.
> Note: if your project's token contains uppercase characters, it will fail due to a bug in the Runner. You can manually set the token further down the CI/CD settings screen. Set it to all lowercase letters and numbers.
1. Save your changes.
Save your changes.
## Deploy GitLab Runner
Use the following yaml files to deploy GitLab Runner:
### Deploy GitLab Runner - can view Pod logs to confirm it registered
Now that we have a Runner configured, we need to kick off a Pipeline. This is because the Prometheus integration only looks for environments which GitLab knows about and have a successful deploy. To do this, go into Pipelines and run a new Pipeline off `master`.
You can view the Pod logs to confirm it registered successfully.
## Run a Pipeline to deploy to an Environment
Now that we have a Runner configured, we need to kick off a Pipeline. This is
because the Prometheus integration only looks for environments which GitLab
knows about and have a successful deploy. To do this, go into Pipelines and run
a new Pipeline off `master`.
You can validate the deploy worked by looking at the Kubernetes dashboard, or accessing the URL.
You can validate the deploy worked by looking at the Kubernetes dashboard, or
accessing the URL.
To retrieve the URL:
```
minikube service production
```
If the deploy failed, you may need to edit the project's runner token to not include capital letters. (See Note in the step above.)
If the deploy failed, you may need to edit the project's runner token to not
include capital letters. (See Note in the step above.)
## Configure Prometheus Service Integration
Finally, we are ready to configure the Prometheus integration.
### Configure Prometheus Service Integration
Finally we are ready to configure the Prometheus integration.. Go into Project Settings, Integrations, and select Prometheus.
1. Go to **Project ➔ Settings ➔ Integrations ➔ Prometheus**.
1. Enter the [Prometheus URL](#get-prometheus-service-url) and click Active.
1. Save and test.
Enter the Prometheus URL from the step above, and click Active. Save and test.
## View Performance metrics
### View Performance metrics
Go to Pipelines, Environments, then click on an Environment. You should see a new button appearing that looks like a chart. Click on it to view the metrics.
Go to **Pipelines ➔ Environments** then click on an Environment. You should see
a new button appearing that looks like a chart. Click on it to view the metrics.
>Note: It may take 30-60 seconds for the Prometheus server to get a few sets of data points.
It may take 30-60 seconds for the Prometheus server to get a few sets of data points.
