Skip to main content

Installation on Kubernetes

The DBmarlin remote agent can run in a Kubernetes pod. It connects to the DBmarlin server's Archiver endpoint and can monitor databases that are reachable from the cluster. A server can also be installed on Kubernetes; see Server installation on Kubernetes.

Container image​

You can use a pre-built image from Docker Hub or build and publish your own image.

Use the public image​

The public image is available at Docker Hub. Kubernetes pulls the image when the Deployment starts, so a separate docker pull is not required.

image: dbmarlin/dbmarlin-agent:latest

For repeatable deployments, replace latest with a specific DBmarlin version tag.

Build your own image​

The DBmarlin Docker repository contains the example agent Dockerfile. Build the image with a DBmarlin version and push it to a registry that your cluster can reach. If the registry is private, configure an image pull secret in the Deployment's namespace.

Kubernetes deployment​

The repository contains a ready-to-customize agent-k8s-deploy.yaml and optional wrapper scripts in the same directory.

Configure the Deployment​

Before applying the manifest, edit the image, environment variables, and resources.

containers:
- name: dbmarlin-agent
  image: dbmarlin/dbmarlin-agent:latest
  env:
  - name: DBMARLIN_AGENT_NAME
    value: "k8s-test-agent"
  - name: DBMARLIN_ARCHIVER_URL
    value: "http://dbmarlin-service:9090/archiver"
  - name: DBMARLIN_API_KEY
    value: "replace-with-base64-encoded-user:pass"

DBMARLIN_AGENT_NAME must be unique for each remote agent and can contain up to 50 characters. If it is omitted, the agent uses the name default, which is reserved for the built-in agent.

DBMARLIN_ARCHIVER_URL is the complete URL of the server Archiver endpoint, including the scheme, host, port, and /archiver path. Use the Kubernetes Service name when the server is in the same cluster, or an externally reachable hostname when it is outside the cluster.

DBMARLIN_API_KEY is the Base64 encoding of username:password when the server uses Nginx Basic Auth. Omit it when authentication is disabled. Do not commit a real credential in the manifest; use a Kubernetes Secret or your deployment system's secret injection mechanism instead.

The example requests 0.5 CPU and 256Mi memory, with limits of 1 CPU and 512Mi. Increase these values when the agent monitors many database targets. Port 9080 must be reachable by the liveness probe and does not normally need a Service.

Apply the Deployment​

Make sure kubectl is using the intended context and namespace, then apply the manifest:

kubectl apply -f agent-k8s-deploy.yaml

The wrapper is equivalent:

./agent-k8s-deploy.sh

Check the rollout and pod logs:

kubectl rollout status deployment/dbmarlin-agent
kubectl get pods -l app=dbmarlin-agent
kubectl logs deployment/dbmarlin-agent

Remove the Deployment​

Removing the Deployment stops the agent pod. The agent has no persistent data volume.

kubectl delete deployment dbmarlin-agent

The wrapper is equivalent:

./agent-k8s-remove-all.sh

Connect to a server outside Kubernetes​

The pod must be able to resolve and reach the server's Archiver URL. If the server is outside the cluster, use its DNS name directly or create an ExternalName Service:

apiVersion: v1
kind: Service
metadata:
  name: staging1-external-service
spec:
  type: ExternalName
  externalName: staging1.dbmarlin.com
  ports:
  - name: archiver
    protocol: TCP
    port: 9090
    targetPort: 9090

Then set:

value: "http://staging1-external-service:9090/archiver"

An ExternalName only provides DNS inside the cluster; it does not create a route, firewall rule, or load balancer. Confirm that cluster egress and the server firewall allow the connection.

Secure Archiver communication with TLS​

When the server uses HTTPS with a certificate signed by a private Certificate Authority, add that CA certificate to the Java truststore used by the agent image. For a public certificate authority, the image's default truststore is normally sufficient. Configure the URL with https:// and verify the certificate name from inside the pod.

Troubleshooting​

  1. The pod is Pending or cannot start. Run kubectl describe pod and check resource scheduling, image pull errors, namespace quotas, and image pull secrets.

  2. The agent does not appear in DBmarlin. Check the Archiver URL, API key, and pod logs:

    kubectl logs deployment/dbmarlin-agent

    From the server, the agent list is available at http://<server-host>:9090/archiver/rest/v1/agent when that endpoint is exposed.

  3. The agent cannot reach the server. Open a shell in the pod and test DNS and the destination port. The image includes curl:

    kubectl exec -it deployment/dbmarlin-agent -- /bin/bash
    curl -v telnet://dbmarlin-service:9090

  4. The agent cannot reach a monitored database. Test the database hostname and port from the agent pod. Kubernetes NetworkPolicies, namespace DNS, cloud security groups, and database firewalls can all block this traffic.