Onboarding services automatically

Gremlin can automatically discover and onboard services that you have annotated. Annotations are metadata that you can add to hosts, containers, and Kubernetes resources. When the Gremlin agent detects these annotations, it uses them to create and name services, which you can then run reliability tests on. This makes it easy to onboard a large number of services—and automatically onboard new services—to your Gremlin team.

‍

Supported annotations

Gremlin supports three different types of annotations, all starting with the prefix gremlin.com/:

• service-id: the name that you want to give the service when it's onboarded to Gremlin.
• team-id: the ID of the Gremlin team that owns the service.
• tags: any additional tags that you want to give the service.

‍

Annotating host-based services

You can register host-based services with Gremlin by adding the gremlin-service-id tag to your agent configuration. Each host that shares the same gremlin-service-id value will be treated as part of the same service.

1. Identify the host(s) that you want to annotate.
2. Choose a name for the service. This is the name that the service will have in the Gremlin web app and REST API. This can be the hostname, the name of the cluster the host belongs to, or a unique name specific to Gremlin.
3. Add the tag to the agent configuration. An example is available below.
   
   1. Alternatively, use the GREMLIN_CLIENT_TAGS environment variable, also shown below.
   2. (Optional) You can include multiple hosts in a single service by reusing the same service name across each host's agent configuration.
4. Save the updated configuration(s) and restart the agent(s). Gremlin will detect the annotations and create the new service.

# config.yaml
identifier: gremlin-01
team_id: 11111111-1111-1111-1111-111111111111

tags:
  gremlin-service-id: my-nginx-service

‍

Alternatively, you can use the GREMLIN_CLIENT_TAGS environment variable:

GREMLIN_CLIENT_TAGS="gremlin-service-id=my-nginx-service"

‍

Annotating Kubernetes-based services

​​You can register Kubernetes objects with Gremlin by adding the gremlin.com/service-id annotation. Each object with the same service-id  value will be treated as part of the same service.

1. Identify the Kubernetes resource(s) that you want to annotate. Gremlin supports annotations on Deployments, DeploymentConfigs, DaemonSets, StatefulSets, and Argo Rollouts.
2. Choose a name for the service. This is the name that the service will have in the Gremlin web app and REST API. This can be the same name as the Kubernetes object, or a unique name specific to Gremlin.
3. Add the annotation to the object definition. An example is available below.
   
   1. (Optional) If you want multiple objects to be part of the same service (e.g. two or more Deployments), use the same service name for both.
   2. (Optional) If you want to create this service for another team in your company, add the gremlin.com/team-id annotation. The value of this annotation should be the ID of the team within your company that you want to create the service for. Remember to share access to the namespace with that team before doing so, otherwise the service will not be automatically generated.
   3. (Optional) You can add additional tags to this service by adding a gremlin.com/tags annotation containing a comma-separated list of key-value pairs. For example: gremlin.com/tags: environment:staging,app:nginx. This is useful for organizing and searching services in the Gremlin web app.
4. Deploy the updated manifest. The Gremlin agent will detect the annotation and add the new service.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  labels:
    app: nginx
  annotations:
    gremlin.com/service-id: my-nginx-service
    gremlin.com/team-id: my-team-id
    gremlin.com/tags: environment:production,app:nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.14.2
          ports:
            - containerPort: 80

‍

Bulk annotating services

If you have a large number of deployments to annotate, you can use a script similar to the one below. This script iterates over each deployment in a given namespace, annotates the deployment using the deployment name as the service name, and adds any additional tags that you want to give the service (deployment environment, region, etc.). If you don’t want to add tags, remove the GREMLIN_TAGS="..." and gremlin.com/tags="..." lines.

#!/usr/bin/env bash

# ─── Configuration ────────────────────────────────────────────
NAMESPACE="your_namespace"
GREMLIN_TAGS="custom_tag_key:custom_tag_value,custom_tag_key1:custom_tag_value1"
# ──────────────────────────────────────────────────────────────

kubectl get deployments -n "$NAMESPACE" --no-headers -o custom-columns=":metadata.name" | while read deployment; do
  echo "Annotating $deployment with service-id: $deployment"

  kubectl annotate deployment "$deployment" \
    -n "$NAMESPACE" \
    gremlin.com/service-id="$deployment" \
    gremlin.com/tags="$GREMLIN_TAGS" \
    --overwrite

done

‍