YouTrack Server 2024.3 Help

Deploy YouTrack with Kubernetes

This guide provides instructions that you can follow to deploy YouTrack to a Kubernetes cluster.

This information is intended for use by administrators who are currently working with Kubernetes to manage an application ecosystem or are interested in migrating their applications to the popular cloud-native container orchestration system.

The instructions provided here describe how to set up a YouTrack instance in a Docker container on a single-node Kubernetes cluster. Multi-node installations are not supported at this time, but we have plans to support them in the future.

Prerequisites

Before you start to deploy YouTrack to your Kubernetes cluster, ensure that you have everything you need to get started.

  1. First, you will need to pull an image of the latest YouTrack version from the Docker YouTrack Repository using docker pull command:

    docker pull jetbrains/youtrack:<version>

    Replace <version> with the complete version number and build. For a complete list of release versions, check Docker Hub.

  2. You will need kubectl, a command-line tool that lets you run commands for the Kubernetes cluster. If you haven't already installed it, follow these instructions.

Installation in a Local Environment

There are various tools that you can use to set up a local Kubernetes cluster and deploy an application inside your network. Here, we provide instructions for Docker Desktop, kind, and minikube.

Each tool provides the same result, so feel free to follow the instructions for whichever tool you are most comfortable using.

Docker Desktop lets you run a Kubernetes cluster without having to configure the cluster manually. If you are already using Docker Desktop, this is the easiest approach. Make sure that Kubernetes is enabled on your Docker Desktop:

  1. After installing Docker Desktop, click the Docker icon in your menu bar and navigate to Preferences > Kubernetes.

  2. Select the Enable Kubernetes checkbox.

  3. Click Apply & Restart.

Docker Desktop will automatically set up Kubernetes for you. To confirm that Kubernetes has been enabled successfully, check for a green light next to the label for Kubernetes.

kind is a tool for running local Kubernetes clusters using Docker container β€œnodes”. It was primarily designed for testing Kubernetes itself, but may be used for local development or CI.

kind starts the Kubernetes cluster with one node inside the virtual machine locally.

  1. Install kind.

  2. Use the following command to run kind and create a cluster:

    kind create cluster

You should see the following information posted in the console output:

Creating cluster "kind" ... βœ“ Ensuring node image (kindest/node:v1.25.0) πŸ–Ό βœ“ Preparing nodes πŸ“¦ βœ“ Writing configuration πŸ“œ βœ“ Starting control-plane πŸ•ΉοΈ βœ“ Installing CNI πŸ”Œ βœ“ Installing StorageClass πŸ’Ύ Set kubectl context to "kind-kind" You can now use your cluster with: kubectl cluster-info --context kind-kind

You can start a Kubernetes cluster locally with minikube, another tool designed to work with Kubernetes in a local environment.

  • Install minikube.

  • Use the following command to run minikube and create a cluster:

    minikube start

You should see the following information posted in the console output:

Starting local Kubernetes cluster... Running pre-create checks... Creating machine... Starting local Kubernetes cluster...

Describing Apps with Kubernetes YAML

All Kubernetes objects should be described in manifests called Kubernetes YAML files. To run and manage the YouTrack application, you need to create a youtrack-config.yaml file.

apiVersion: v1 kind: Deployment metadata: name: youtrack-deployment namespace: default labels: app: youtrack spec: replicas: 1 strategy: type: Recreate selector: matchLabels: app: youtrack bb: web template: metadata: labels: app: youtrack spec: containers: - name: youtrack image: jetbrains/youtrack:[youtrack-version]. --- apiVersion: v1 kind: Service metadata: name: youtrack-entrypoint namespace: default spec: type: NodePort ports: - port: [port] targetPort: [port] nodePort: [nodePort]

The Deployment section describes a scalable group of identical pods.

  • The replicas configuration denotes that there is only one copy of your pod.

  • The pod itself is described in the template.

  • The containers section has just one container that is based on your jetbrains/youtrack:[youtrack-version] Docker image.

The second part of the file defines a NodePort service that routes traffic from a [nodePort] on your host to a [port] port inside the pods it routes to. This gives you the ability to access the YouTrack application from the network.

Traffic Routing

Alternatively, you can replace the NodePort traffic routing service using Ingress. Ingress provides a more reliable solution aimed at constant service availability. With this approach, each service is assigned its own IP address. This lets you route traffic to backend services based on their paths and subdomains.

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: youtrack-ingress annotations: kubernetes.io/ingress.class: "nginx" nginx.ingress.kubernetes.io/backend-protocol: "HTTP" spec: rules: - host: myyoutrackdomain.com http: paths: - path: /youtrack/?(.*) pathType: Prefix backend: service: name: youtrack-entrypoint port: number: [port]

Be sure to check which annotations you need to specify in the metadata section. Annotations are used to configure some options which depend on your Ingress controller. Pay attention to the correct path specification for your particular case as well. For more detailed differences in various approaches, please refer to the Kubernetes documentation.

Provide Persistent Volumes to the Application

Files under the directories provided in this section are persisted. You may lose data from other directories on reboots. For this step, administrator access rights are required. Persistent volumes provisioning can be done in two ways:

Static

Persistent volumes are configured to carry the details of the real storage, which is available for use by cluster users.

Dynamic

The cluster dynamically creates a volume especially for each persistent volume claim.

Without dynamic provisioning, you have to manually make calls to the cloud or storage provider to create new storage volumes, and then create PersistentVolume objects to represent them in Kubernetes. Dynamic provisioning automatically provisions storage when it is requested by users.

As dynamic provisioning is considered to be the best practice we recommend using it. For more information, please refer to the Kubernetes documentation.

Dynamic Storage Provisioning

To enable dynamic provisioning, you need to pre-create one or more StorageClass objects for users. The name of a StorageClass object must be a valid DNS subdomain name.

apiVersion: v1 kind: StorageClass metadata: name: youtrack-storage-class provisioner: kubernetes.io/gce-pd parameters: type: pd-ssd

Include a storage class in the PersistentVolumeClaim:

apiVersion: v1 kind: PersistentVolumeClaim metadata: name: youtrack-data-pv-claim namespace: default spec: accessModes: - ReadWriteOnce storageClassName: storage-class-1 resources: requests: storage: 1Gi

This claim results in the automatic provisioning of an SSD-like Persistent Disk. When the claim is deleted, the volume is destroyed.

You should create four persistent volume claims (PVCs) for each of the directories YouTrack uses to store application files: data, conf, backups, and logs.

Dynamic provisioning can enable all claims to be dynamically provisioned if no storage class is specified. To do that, the following is required:

  1. Designate one StorageClass object as the default by adding the storageclass.kubernetes.io/is-default-class annotation to it.

  2. Make sure that the DefaultStorageClass admission controller is enabled on the API server.

To learn more, refer to the Kubernetes documentation.

Pods access storage by using the claim as a volume. Claims must exist in the same namespace as the pod using the claim. The cluster gets the PV from the PVC, which is mounted to the host and into the pod. You can add volumes to the deployment configuration in the youtrack-config.yaml file:

apiVersion: v1 kind: Deployment metadata: name: youtrack-deployment namespace: default labels: app: youtrack spec: replicas: 1 selector: matchLabels: app: youtrack bb: web template: metadata: labels: app: youtrack spec: containers: - name: youtrack image: jetbrains/youtrack:[youtrack-version] volumeMounts: - name: opt-youtrack-data mountPath: /opt/youtrack/data - name: opt-youtrack-conf mountPath: /opt/youtrack/conf - name: opt-youtrack-logs mountPath: /opt/youtrack/logs - name: opt-youtrack-backups mountPath: /opt/youtrack/backups volumes: - name: opt-youtrack-data persistentVolumeClaim: claimName:youtrack-data-pv-claim - name: opt-youtrack-conf persistentVolumeClaim: claimName:youtrack-conf-pv-claim - name: opt-youtrack-logs persistentVolumeClaim: claimName:youtrack-logs-pv-claim - name: opt-youtrack-backups persistentVolumeClaim: claimName: youtrack-backups-pv-claim

Deploy and Check Your Application

In a command-line interface, navigate to the folder where you created the youtrack-config.yaml file and deploy your application to Kubernetes:

$ kubectl apply -f youtrack-config.yaml

If the Kubernetes objects were created successfully, the following information is posted to the console:

deployment.apps/youtrack-deployment created service/youtrack-entrypoint created

USe the following command to list all the deployments and verify that the pods described in the YAML file are up and running:

$ kubectl get deployments

Use the following command to verify that the services are running as well:

$ kubectl get services

Installation in a Managed Kubernetes Service

Managed Kubernetes services are used to run, deploy, and operate Kubernetes clusters. Popular services include the Amazon Elastic Kubernetes Service, Microsoft Azure Kubernetes Service, Oracle Container Engine for Kubernetes, and Google Kubernetes Engine.

When working with a managed Kubernetes service, you need to make sure your worker nodes are using supported container runtimes. If you have node customizations, you may need to update them based on your environment and runtime requirements.

Google Kubernetes Engine

Use this setup to run a YouTrack container image on a Google Kubernetes Engine (GKE) cluster.

Preparatory work

  1. To run commands, you need to activate the Google Cloud Shell. Click the Activate Cloud Shell icon in the application header of the Google Cloud Console.

  2. Select or create a Google Cloud project. If you experience any troubles during this stage, please refer to the Google Cloud documentation.

    • Use the following command to create a project in Google Cloud:

      gcloud projects create PROJECT_ID
    • Use the following command to select an existing project:

      gcloud config set PROJECT_ID
  3. Make sure that billing is enabled for your Cloud project. To learn how, please refer to the Google Cloud documentation.

  4. Use the following command to enable the Artifact Registry and Google Kubernetes Engine API:

    gcloud services enable artifactregistry.googleapis.com container.googleapis.com
  5. First, you will need to pull an image of the latest YouTrack version from the Docker YouTrack Repository using docker pull command:

    docker pull jetbrains/youtrack:<version>

    Replace <version> with the complete version number and build. For a complete list of release versions, check Docker Hub.

  6. Run the docker images command to verify that the build was successful:

    docker images

    In the output you should see jetbrains/youtrack:{version} among your loaded images:

    REPOSITORY TAG IMAGE ID CREATED SIZE jetbrains/youtrack 2022.1.42540 82c55a0fdf90 2 days ago 719MB

Deploy the YouTrack Image to the Cluster

  1. Create a Kubernetes cluster or select a cluster that was created previously.

  2. Use the following command to verify that you are connected to your GKE cluster.

    gcloud container clusters get-credentials [cluster-name] --zone [zone]
  3. Create a Kubernetes Deployment so you can run the YouTrack application on the cluster.

    kubectl create deployment youtrack-app --image=jetbrains/youtrack:{version}
  4. Create a StorageClass configuration in a youtrack-storage-class.yaml file:

    apiVersion: v1 kind: StorageClass metadata: name: youtrack-storage-class provisioner: kubernetes.io/gce-pd parameters: type: pd-ssd

    Apply the configuration:

    kubectl apply -f youtrack-storage-class.yaml
  5. Create persistent volume claim (PVC) configurations for the data, config, logs and backup directories:

    For example, use the following command to create the data PVC configuration file:

    nano pvc-data.yaml

    Then add this content to the file:

    β€”----- apiVersion: v1 kind: PersistentVolumeClaim metadata: name: youtrack-data-pv-claim namespace: default spec: accessModes: - ReadWriteOnce storageClassName: storage-class-1 resources: requests: storage: 1Gi

    Use the following command to apply the configuration:

    kubectl apply -f pvc-data.yaml
  6. New PVs are generated based on the newly created PVCs. To verify their creation, check Storage > [select desired PVC] > Volume.

  7. You need to attach the PV to the Deployment. To perform this step, navigate to Workloads > [select deployment] > YAML > Edit and insert the following:

    volumeMounts: - mountPath: /opt/youtrack/data name: [data volume name] - mountPath: /opt/youtrack/conf name: [conf volume name] - mountPath: /opt/youtrack/logs name: [logs volume name] - mountPath: /opt/youtrack/backups name: [backup volume name] … volumes: - name: [data volume name] persistentVolumeClaim: claimName: youtrack-data-pv-claim - name: [logs volume name] persistentVolumeClaim: claimName: youtrack-logs-pv-claim - name: [backups volume name] persistentVolumeClaim: claimName: youtrack-backups-pv-claim - name: [conf volume name] persistentVolumeClaim: claimName: youtrack-conf-pv-claim

You should now see corresponding volumes in the Pod specification in your Deployment.

Exposing the Application

Due to the specific nature of the Google Cloud service, the set of IP addresses that correspond to the active set of Pods is dynamic. You can expose a group of Pods outside the Kubernetes cluster with Services. This feature groups Pods into one static IP address, which can be reached from any Pod inside the cluster. The static IP address also is assigned a DNS hostname, for example, youtrack-app.default.svc.cluster.local.

kubectl expose deployment youtrack-app --name=test-service --type=LoadBalancer --port 80 --target-port 8080

To get more details about the service run:

kubectl get service

You should receive an output like this:

NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE hello-app-service 10.3.251.122 213.1.234.0 80:30878/TCP 11s

After that, you can open a new browser tab and navigate to the EXTERNAL-IP:PORT, where PORT is equal to the target-port that you defined in the kubectl expose command. There you will see a Setup Wizard that lets you continue installing the YouTrack application.

Troubleshooting

If you encounter problems with the installation, see if any of the following conditions apply.

Condition β€” You encounter a CrashLoopBackOff error.

Cause

Solution

The pod may be crashing because it starts up and exits immediately afterward, then Kubernetes restarts and the cycle continues. For more details please check the Pod Lifecycle documentation.

Add a command like sleep to the volumeMounts section of the YAML file to keep the container alive.

volumeMounts: - mountPath: /opt/youtrack/conf name: [conf volume name] … command: ["/bin/sh"] # add command args: ["-c", "sleep 60"] # sleep command for 60 seconds

Condition β€” The error directory opt/youtrack/data is not writable.

Cause

Solution

The directory doesn't exist or you don't have sufficient permissions.

  1. Check if the directory exists.

  2. Use the following command to set the permissions for the directory:

    chown -R 13001:13001 [directory name]
Last modified: 02 April 2024