diff options
Diffstat (limited to 'doc/operations/quickstart-guide.md')
| -rw-r--r-- | doc/operations/quickstart-guide.md | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/doc/operations/quickstart-guide.md b/doc/operations/quickstart-guide.md new file mode 100644 index 00000000000..91c5f25405c --- /dev/null +++ b/doc/operations/quickstart-guide.md @@ -0,0 +1,229 @@ +--- +stage: Monitor +group: Observability +info: 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](https://gitlab.com/gitlab-org/opstrace/opstrace.git) 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](#install-dependencies-using-asdf): + +- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) for creating a local Kubernetes cluster. +- [Docker](https://docs.docker.com/install) + - [Docker Compose](https://docs.docker.com/compose/compose-v2/) is now part of the `docker` distribution. +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) for interacting with GitLab Observability. +- [Telepresence](https://www.telepresence.io/) allows you to code and test microservices locally against a remote Kubernetes cluster. +- [jq](https://stedolan.github.io/jq/download/) for some Makefile utilities. +- [Go 1.19](https://go.dev/doc/install). + +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: + +```shell +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`](https://asdf-vm.com/#/core-manage-asdf), GOP manages them for you automatically. + +1. If you have not already done so, clone the `opstrace` repository into your preferred location: + + ```shell + git clone https://gitlab.com/gitlab-org/opstrace/opstrace.git + ``` + +1. Change into the project directory: + + ```shell + cd opstrace + ``` + +1. Optional. If you need to install `asdf`, run: + + ```shell + make install-asdf + ``` + +1. Install dependencies using `asdf`: + + ```shell + 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: + +```shell +make kind +``` + +Wait a few minutes while kind creates your Kubernetes cluster. When it's finished, you should see the following message: + +```plaintext +Traffic Manager installed successfully +``` + +Now deploy the scheduler by running the following command in the `opstrace` project: + +```shell +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](../integration/oauth_provider.md). +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. + +1. Run the following command to create the secret that holds the authentication data: + + ```shell + 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 + ``` + +1. 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](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91928). +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: + + ```shell + 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 + ``` + +1. Apply the file you just created with the following command: + + ```shell + kubectl apply -f Cluster.yaml + ``` + +1. Run the following command to wait for the cluster to be ready: + + ```shell + 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](https://gitlab.com/gitlab-org/opstrace/opstrace/-/blob/main/docs/guides/user/sending-traces-locally.md). + +## Step 6: Clean up your local GOP + +To tear down your locally running GOP instance, run the following command: + +```shell +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](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/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: + + ```Dockerfile + FROM --platform=arm64 kindest/node:v1.23.13 + RUN arch + ``` + +1. Save your Dockerfile, then build the image with the following command: + + ```shell + docker build -t tempkind . + ``` + + Do not forget the period at the end. + +1. Create a cluster using your new image with the following command: + + ```shell + 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: + +```shell +make kind +export CI_COMMIT_TAG=0.2.0-e1206acf +make deploy +``` |