debian-mirror-gitlab/doc/operations/quickstart-guide.md

stage	group	info
Monitor	Observability	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments

GitLab Observability Quickstart

You can try GitLab Observability by cloning or forking the project and creating a local installation.

Prerequisites and dependencies

To install GitLab Observability Platform (GOP), install and configure the following third-party dependencies. You can do this manually, or automatically by using asdf:

• kind for creating a local Kubernetes cluster.
• Docker
  • Docker Compose is now part of the docker distribution.
• kubectl for interacting with GitLab Observability.
• Telepresence allows you to code and test microservices locally against a remote Kubernetes cluster.
• jq for some Makefile utilities.
• Go 1.19.

The current versions of these dependencies are pinned in the .tool-versions file in the project.

You can run the following commands to check the availability and versions of these dependencies on your machine:

kind --version
docker --version
kubectl version
telepresence version
jq --version
go version

Run GOP on macOS

If you're running GOP on macOS, ensure you have enough resources dedicated to Docker Desktop. The recommended minimum is:

• CPUs: 4+
• Memory: 8 GB+
• Swap: 1 GB+

It's possible to run GOP with fewer resources, but this specification works.

Install dependencies using asdf

If you install dependencies using asdf, GOP manages them for you automatically.

1. If you have not already done so, clone the opstrace repository into your preferred location:

   git clone https://gitlab.com/gitlab-org/opstrace/opstrace.git
   

2. Change into the project directory:

   cd opstrace
   

3. Optional. If you need to install asdf, run:

   make install-asdf
   

4. Install dependencies using asdf:

   make bootstrap
   

Step 1: Create a local Kubernetes cluster with kind

Make sure Docker Desktop is running. In the opstrace project you cloned, run the following command:

make kind

Wait a few minutes while kind creates your Kubernetes cluster. When it's finished, you should see the following message:

Traffic Manager installed successfully

Now deploy the scheduler by running the following command in the opstrace project:

make deploy

This takes around 1 minute.

Step 2: Create a GitLab application for authentication

You must create a GitLab application to use for authentication.

In the GitLab instance you'd like to connect with GOP, create an OAuth application. This application can be a user-owned, group-owned or instance-wide application. In production, you would create a trusted instance-wide application so that users are explicitly authorized without the consent screen. The following example shows how to configure the application.

1. Select the API scope and enter http://localhost/v1/auth/callback as the redirect URI.

2. Run the following command to create the secret that holds the authentication data:

   kubectl create secret generic \
       --from-literal=gitlab_oauth_client_id=<gitlab_application_client_id> \
       --from-literal=gitlab_oauth_client_secret=<gitlab_application_client_secret> \
       --from-literal=internal_endpoint_token=<error_tracking_internal_endpoint_token> \
        dev-secret
   

3. Replace <gitlab_application_client_id> and <gitlab_application_client_secret> with the values from the GitLab application you just created. Replace <error_tracking_internal_endpoint_token> with any string if you do not plan to use error tracking.

You can also view this MR on how to get the token to test error tracking. You must specify all the parameters when creating the secret.

Step 3: Create the cluster definition

1. In your opstrace project, run the following command to create a Cluster.yaml manifest file:

   cat <<EOF > Cluster.yaml
   apiVersion: opstrace.com/v1alpha1
   kind: Cluster
   metadata:
     name: dev-cluster
   spec:
     target: kind
     goui:
       image: "registry.gitlab.com/gitlab-org/opstrace/opstrace-ui/   gitlab-observability-ui:c9fb6e70"
     dns:
       acmeEmail: ""
       dns01Challenge: {}
       externalDNSProvider: {}
     gitlab:
       groupAllowedAccess: '*'
       groupAllowedSystemAccess: "6543"
       instanceUrl: https://gitlab.com
       authSecret:
         name: dev-secret
   EOF
   

2. Apply the file you just created with the following command:

   kubectl apply -f Cluster.yaml
   

3. Run the following command to wait for the cluster to be ready:

   kubectl wait --for=condition=ready cluster/dev-cluster --timeout=600s
   

After the previous command exits, the cluster is ready.

Step 4: Enable Observability on a GitLab namespace you own

Go to a namespace you own in the connected GitLab instance and copy the Group ID below the group name.

GOP can only be enabled for groups you own. To list all the groups that your user owns, go to the menu in upper left corner and select Groups->View all Groups. You then see the Your groups tab.

In your browser, go to http://localhost/-/{GroupID}. For example, http://localhost/-/14485840.

Follow the on-screen instructions to enable observability for the namespace. This can take a couple of minutes if it's the first time observability has been enabled for the root level namespace (GitLab.org in the previous example.)

Once your namespace has been enabled and is ready, the page automatically redirects you to the GitLab Observability UI.

Step 5: Send traces to GOP

Follow this guide to send traces to your namespace and monitor them in the UI.

Step 6: Clean up your local GOP

To tear down your locally running GOP instance, run the following command:

make destroy

Known issues

Incorrect architecture for kind/node image

If your machine has an Apple silicon (M1/M2) chip, you might encounter an architecture problem with the kind/node image when running the make kind command. For more details, see issue 1802.

To fix this problem, you first need to create a Dockerfile. Then build and deploy the image:

1. Create a new Dockerfile (without a file extension) and paste the following commands:

   FROM --platform=arm64 kindest/node:v1.23.13
   RUN arch
   

2. Save your Dockerfile, then build the image with the following command:

   docker build -t tempkind .
   

   Do not forget the period at the end.

3. Create a cluster using your new image with the following command:

   kind create cluster --image tempkind
   

scheduler-controller-manager pod cannot start due to ImagePullBackOff

If while executing make deploy in step 1, the scheduler-controller-manager pod cannot start due to ImagePullBackOff, you must set the CI_COMMIT_TAG to a non-dirty state. By setting the commit tag to the latest commit, you ensure the Docker image can be pulled from the container registry.

Run the following command to set the commit tag:

make kind
export CI_COMMIT_TAG=0.2.0-e1206acf
make deploy