Skip to content
Snippets Groups Projects
Commit 7ab41fb7 authored by Arun Sori's avatar Arun Sori
Browse files

Merge branch 'docs/catherinepope-move-quickstart' into 'main'

Replace quick start with polished version

See merge request !1970



Merged-by: default avatarArun Sori <asori@gitlab.com>
Approved-by: Kevin Chu's avatarKevin Chu <kchu@gitlab.com>
Approved-by: default avatarArun Sori <asori@gitlab.com>
Co-authored-by: default avatardrcatherinepope <cpope@gitlab.com>
parents 76b27ad7 4e1870b0
No related branches found
No related tags found
1 merge request!1970Replace quick start with polished version
# GitLab Observability Quick Start
Try GitLab Observability by cloning or forking this repo and creating a local installation.
You can try GitLab Observability by [cloning or forking the project](https://gitlab.com/gitlab-org/opstrace/opstrace.git) and creating a local installation.
## Step 0: Setup
## Prerequisites and dependencies
### Install 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):
Before setting up GitLab Observability Platform components, you must have the following third-party dependencies installed and configured.
These can be done manually by yourself OR [automatically using asdf](#automatically-using-asdf).
#### Automatically using `asdf`
Installing dependencies using [`asdf`](https://asdf-vm.com/#/core-manage-asdf) lets GitLab Observability manage them for you automatically:
1. Clone this repository into your preferred location, if you haven't previously:
```shell
git clone gitlab-org/opstrace/opstrace.git
```
1. Change into the project directory:
```shell
cd opstrace
```
1. Install dependencies using `asdf`:
If you already have `asdf` installed, run:
* [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).
```shell
make bootstrap
```
The current versions of these dependencies are pinned in the `.tool-versions` file in the project.
If you need to install `asdf` as well, run:
You can run the following commands to check the availability and versions of these dependencies on your machine:
```shell
make install-asdf
```
Do not forget to source your profile as suggested by the command above, then run `make bootstrap` to get all dependencies.
> We currently use versions of these dependencies as pinned in the `.tool-versions` file.
In any case, make sure you have the following:
* [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) for setting up 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 remote network interception for local dev.
* [jq](https://stedolan.github.io/jq/download/) for some makefile utilities.
* [Go 1.19](https://go.dev/doc/install).
```bash
kind --version
docker --version
kubectl version
......@@ -63,281 +27,197 @@ jq --version
go version
```
If running on MacOS, be sure to make sure you have enough resources dedicated to docker desktop.
We recommend:
### 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: 8GB+
* Swap: 1GB+
* Memory: 8 GB+
* Swap: 1 GB+
It's possible to run with lower resources, we just know that these work.
It's possible to run GOP with fewer resources, but this specification works.
Now we need to create a local kind cluster
### Install dependencies using asdf
```bash
make kind
```
If you install dependencies using [`asdf`](https://asdf-vm.com/#/core-manage-asdf), GOP manages them for you automatically.
## Step 1: Install GitLab Observability
1. If you have not already done so, clone the `opstrace` repository into your preferred location:
Now deploy the scheduler:
```shell
git clone https://gitlab.com/gitlab-org/opstrace/opstrace.git
```
```bash
make deploy
```
1. Change into the project directory:
Create a GitLab Application so we can use it for authentication.
In the GitLab instance you'd like to connect GitLab Observability to, [create an OAuth Application](https://docs.gitlab.com/ee/integration/oauth_provider.html#introduction-to-oauth).
This application can be a user owned, group owned or instance-wide application.
In production, we create an instance-wide application and select "trusted" so that users are explicitly authorized without the consent screen.
Here is an example of how to configure the application.
Be sure to select the API scope and to enter `http://localhost/v1/auth/callback` as the redirect URI:
```shell
cd opstrace
```
![gitlab oauth application](./assets/create-gitlab-application.png)
1. Optional. If you need to install `asdf`, run:
Create the secret holding auth data:
```shell
make install-asdf
```
```bash
kubectl create secret generic \
--from-literal=gitlab_oauth_client_id=<YOUR CLIENT ID FROM YOUR GITLAB APPLICATION> \
--from-literal=gitlab_oauth_client_secret=<YOUR CLIENT SECRET FROM YOUR GITLAB APPLICATION> \
--from-literal=internal_endpoint_token=<ERROR TRACKING INTERNAL ENDPOINT TOKEN> \
dev-secret
```
1. Install dependencies using `asdf`:
Replace `<YOUR CLIENT ID FROM YOUR GITLAB APPLICATION>` and `<YOUR CLIENT SECRET FROM YOUR GITLAB APPLICATION>` with the values from your GitLab application that you just created.
Replace `<ERROR TRACKING INTERNAL ENDPOINT TOKEN>` with any string for if you do not plan to use error tracking.
You can also look at [this](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91928) and see how you can obtain the token to test error tracking.
All the parameters above are not optional - must be set.
Next step is to create the cluster definition:
```bash
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
```
```shell
make bootstrap
```
If you are using locally running GDK, instead of `http://gitlab.com`, `instanceUrl` should point to your local GDK Gitlab instance.
## Step 1: Create a local Kubernetes cluster with kind
```bash
kubectl apply -f Cluster.yaml
```
Make sure Docker Desktop is running. In the `opstrace` project you cloned, run the following command:
Wait for the cluster to be ready:
```bash
kubectl wait --for=condition=ready cluster/dev-cluster --timeout=600s
```shell
make kind
```
Once the above command exits, the cluster is ready.
## Step 2: Enable Observability on a GitLab namespace you own
Navigate to a namespace you own in the connected GitLab instance, and copy the Group ID below the group name, for example:
![copy-group-id](./assets/copy-group-id.png)
Wait a few minutes while kind creates your Kubernetes cluster. When it's finished, you should see the following message:
GOP can only be enabled for groups you own.
In order to list all the groups that your user owns, navigate to menu in upper right corner and select `Groups`->`Your Groups`.
![list-groups](./assets/listing_groups.png)
For the sake of experimentation you can use the [sandbox](https://gitlab.com/gitlab-org/opstrace/sandbox) subgroup. As mentioned above you will need to be an owner of the group. If you are not ask a code owner to add you.
Now open your browser to [http://localhost/-/{GroupID}](http://localhost/-/{GroupID}). In the above group, we'd open [http://localhost/-/14485840](http://localhost/-/14485840)
```plaintext
Traffic Manager installed successfully
```
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 above example.\
There are many optimizations we can make to reduce this provisioning time.
Now deploy the scheduler by running the following command in the `opstrace` project:
Once your namespace has been enabled and is ready, the page will automatically direct you to the GitLab Observability UI.
```shell
make deploy
```
## Step 3: Send traces to GitLab Observability
This takes around 1 minute.
[Follow this guide for sending traces to your namespace and checking them out in the UI.](./guides/user/sending-traces-locally.md)
## Step 2: Create a GitLab application for authentication
## Step 4: Clean up
You must create a GitLab application to use for authentication.
To tear down your locally running instance of GitLab Observability, run:
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.
```bash
make destroy
```
1. Select the API scope and enter `http://localhost/v1/auth/callback` as the redirect URI.
## Running Gitlab Observability UI locally
1. Run the following command to create the secret that holds the authentication data:
There are few extra steps that are needed to enable GOUI embedding when running GOP together with GDK locally.
```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
```
### Step 1: configure GDK
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.
In GDK's root directory, create `env.runit` file if it does not exist already.
Add export `OVERRIDE_OBSERVABILITY_URL=http://localhost`
By default GOP will be available at `http://localhost` when running locally and following this quickstart's steps.
Adjust it to your own instance's address if this is not the case.
Please remember to not to add any trailing slashes to the URL.
Both GDK Gitlab instance and GOUI instance MUST be using the same protocol (http or https).
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.
OPTIONAL:
Untill [this](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/96533) MR gets merged, an extra step is needed - we need to make sure that GDK is running a patched version of Gitlab.
From the root of GDK issue:
## Step 3: Create the cluster definition
```bash
cd gitlab/
git fetch
git checkout rossetd-improve-obs-local-dev
git rebase origin/master
cd ../
```
1. In your `opstrace` project, run the following command to create a `Cluster.yaml` manifest file:
Now we need to restart GDK:
```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
```
```bash
gdk restart
```
1. Apply the file you just created with the following command:
The final step is to enable monitoring feature-flag.
Issue the follwing commands:
```shell
kubectl apply -f Cluster.yaml
```
```bash
gdk rails console
Feature.enable(:observability_group_tab)
```
1. Run the following command to wait for the cluster to be ready:
## Step 2: Apply overrides to GOP tenant
```shell
kubectl wait --for=condition=ready cluster/dev-cluster --timeout=600s
```
The ID of the group we used to provision the Tenant is also the name of the k8s namespace where GOUI pods were launched.
We will be thus refering to this GroupID.
After the previous command exits, the cluster is ready.
Due to the fact that GDK and GOP, when running locally, use different domains (`gdk.test` vs. `localhost`), we need to apply few additional overrides. You can get the tenant's name and namespace (GroupID) using:
## Step 4: Enable Observability on a GitLab namespace you own
```bash
k get tenant --all-namespaces
```
Go to a namespace you own in the connected GitLab instance and copy the Group ID below the group name.
Issue following command, once the tenant gets provisioned:
GOP can only be enabled for groups you own.
To list all the groups that your user owns, in the upper-left corner, select **Groups > View all Groups**. You then see the **Your groups** tab.
```bash
k edit tenant -n <GroupID> <TenantName>
```
In your browser, go to `http://localhost/-/{GroupID}`. For example, `http://localhost/-/14485840`.
and add the following keys:
```yaml
spec:
overrides:
argus:
components:
statefulset:
spec:
template:
spec:
containers:
- image: registry.gitlab.com/gitlab-org/opstrace/opstrace-ui/gitlab-observability-ui:<TAG_TO_TEST>
name: argus
config:
security:
allow_embedding: true
content_security_policy: false
cookie_samesite: none
cookie_secure: true
```
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.)
Values above also illustrate how to override the docker image that GOUI is using.
It is not required to make GOUI work though and can be also done on the `Cluster` object (only relevant fields are shown):
```yaml
apiVersion: opstrace.com/v1alpha1
kind: Cluster
metadata:
name: dev-cluster
namespace: default
spec:
goui:
image: registry.gitlab.com/gitlab-org/opstrace/opstrace-ui/gitlab-observability-ui:<TAG_TO_TEST>
```
Once your namespace has been enabled and is ready, the page automatically redirects you to the GitLab Observability UI.
Once the GOUI pods get restarted, we can verify the changes by:
## Step 5: Send traces to GOP
```bash
$ k exec -ti -n 35 argus-sts-0 -- grep -A5 security /etc/argus/grafana.ini
Defaulted container "argus" out of: argus, argus-plugins-init (init)
[security]
allow_embedding = true
content_security_policy = false
cookie_samesite = none
cookie_secure = true
[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).
[server]
domain = localhost
```
## Step 6: Clean up your local GOP
and
To tear down your locally running GOP instance, run the following command:
```bash
$ k get pod -n 35 argus-sts-0 -o yaml | grep image:
image: registry.gitlab.com/gitlab-org/opstrace/opstrace-ui/gitlab-observability-ui:<TAG_TO_TEST>
image: quay.io/grafana-operator/grafana_plugins_init:0.0.5
image: registry.gitlab.com/gitlab-org/opstrace/opstrace-ui/gitlab-observability-ui:<TAG_TO_TEST>
image: quay.io/grafana-operator/grafana_plugins_init:0.0.5
```shell
make destroy
```
## Step 3: Navigate to GOUI
Once the steps above are done, one can navigate to GOUI by on the `Observability` button in the left panel's menu:
## Known issues
![navigate-to-goui](./assets/navigate_to_goui.png)
### Incorrect architecture for `kind/node` image
and behold!
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).
![goui](./assets/goui.png)
To fix this problem, you first need to create a Dockerfile. Then build and deploy the image:
## Known Issues
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. If you are running on apple silicon (M1/M2) chip, you might face incorrect target architecture for kind/node image while running `make kind`. take a look at this [issue](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/1802)
1. Save your Dockerfile, then build the image with the following command:
Run below command in order to fix it.
create a new Dockerfile
```shell
docker build -t tempkind .
```
```Dockerfile
FROM --platform=arm64 kindest/node:v1.23.13
RUN arch
```
Do not forget the period at the end.
then build it via
1. Create a cluster using your new image with the following command:
```bash
docker build -t tempkind .
```
```shell
kind create cluster --image tempkind
```
Then run to create a cluster.
### scheduler-controller-manager pod cannot start due to ImagePullBackOff
```bash
kind create cluster --image tempkind
```
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.
2. If while executing `make deploy` on step 1 the scheduler-controller-manager pod cannot start due to ImagePullBackOff, then you need to set the CI_COMMIT_TAG to a non dirty state. By setting the commit tag to the latest commit you ensure that the docker image can be pulled from the container registry.
Run the following command to set the commit tag:
```bash
```shell
make kind
export CI_COMMIT_TAG=0.2.0-e1206acf
make deploy
```
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment