Migrate to the unified gateway deployment for NGINX and GEM gateway in Helm
Version 4.0.0
of the mimir-distributed
Helm chart adds a new way to deploy the NGINX reverse proxy in front of
Mimir. The NGINX configuration was unified with the GEM (Grafana Enterprise Metrics) gateway configuration. Using a
single section makes it possible to migrate from Mimir to GEM without downtime.
The unification also brings new features to the GEM gateway: OpenShift Route and horizontal autoscaling of the gateway Pods.
The unified configuration lives in the gateway
section of the values file. With this we also
deprecate the nginx
section. It will be removed in mimir-distributed
version 7.0.0
.
It is possible to migrate from nginx
to the gateway
configuration without downtime too. The migration should take
less than 30 minutes. The rest of this article contains a procedure for migrating from the old nignx
section to
gateway
.
Before you begin
Make sure that the version of the mimir-distributed
Helm chart that you have installed is 4.0.0
or higher.
Procedure
Scale out the
gateway
deployment:Change your Helm chart values file to enable the
gateway
and increase its replicas:- Set the number of replicas of the gateway Deployment to the number of replicas that NGINX is running with.
For example, if you have deployed 10 NGINX replicas, then add the following configuration to your Helm chart values file
custom.yaml
:gateway: enabledNonEnterprise: true replicas: 10
Deploy your changes:
helm upgrade $RELEASE grafana/mimir-distributed -f custom.yaml
Replace the
nginx
deployment withgateway
:Disable NGINX by adding or merging the following configuration with your values file:
nginx: enabled: false
If you are using the Ingress that the Helm chart provides, then copy the
ingress
section fromnginx
togateway
, and override the name to the name of the Ingress resource that the Helm chart created for NGINX or the GEM gateway.Reusing the name allows the
helm
command to retain the existing resource instead of deleting it and recreating it under a slightly different name. Retaining the existing resource means that the Ingress Controller in your Kubernetes cluster does not need to delete and recreate the backing resources for the Ingress, which might take time depending on which Ingress Controller you use.In the example that follows, the name of the Ingress resource was
mimir-nginx
. Usekubectl
to get the name of the existing Ingress resource:kubectl get ingress
NAME CLASS HOSTS ADDRESS PORTS AGE mimir-nginx <none> mimir.example.com 10.0.0.1 80, 443 172d
The Helm chart values for
gateway
should look similar to this:gateway: ingress: enabled: true nameOverride: mimir-nginx hosts: - host: mimir.example.com paths: - path: / pathType: Prefix tls: - secretName: mimir-gateway-tls hosts: - mimir.example.com enabledNonEnterprise: true replicas: 10
Update the
service
section.If you are overriding anything in the
nginx.service
section, then copy the contents ofnginx.service
section fromnginx
togateway
.Next, override the resource name to the name of the Service resource that the chart created for NGINX. Reusing the name allows the
helm
command to retain the existing resource instead of deleting it and recreating it under a slightly different name. Reusing the name also allows existing clients within the Kubernetes cluster to keep using the nginx Service address without disruption.In the example that follows, the name of the Service resource was
mimir-nginx
. Usekubectl
to get the name of the existing Service resource:kubecl get service
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE mimir-nginx ClusterIP 10.188.8.32 <none> 8080/TCP,9095/TCP 172d
After carrying out this step the Helm values for
gateway
should look like the following:gateway: service: annotations: networking.istio.io/exportTo: admin nameOverride: mimir-nginx ingress: enabled: true nameOverride: mimir-nginx hosts: - host: mimir.example.com paths: - path: / pathType: Prefix tls: - secretName: mimir-gateway-tls hosts: - mimir.example.com enabledNonEnterprise: true replicas: 10
Update the readiness probe endpoint if you are overriding
nginx.nginxConfig
.The readiness probe in the
gateway
setup uses the/ready
endpoint on the containers. Version4.0.0
ofmimir-distributed
configures the NGINX to serve this endpoint. In versions prior to that that endpoint does not exist. If you have copied the contents ofnginx.nginxConfig
into your values file prior to version4.0.0
, then you need to correct the readiness probe.After carrying out this step the Helm values for
gateway
should look like the following:gateway: readinessProbe: httpGet: path: / service: annotations: networking.istio.io/exportTo: admin nameOverride: mimir-nginx ingress: enabled: true nameOverride: mimir-nginx hosts: - host: mimir.example.com paths: - path: / pathType: Prefix tls: - secretName: mimir-gateway-tls hosts: - mimir.example.com enabledNonEnterprise: true replicas: 10
Move the rest of your values according the following table:
Deprecated field New field Notes nginx.affinity
gateway.affinity
Previously affinity
was a string. Now it should be a YAML object.nginx.annotations
gateway.annotations
nginx.autoscaling
gateway.autoscaling
nginx.basicAuth
gateway.nginx.basicAuth
Nested under proxy.nginx
.nginx.containerSecurityContext
gateway.containerSecurityContext
nginx.deploymentStrategy
gateway.strategy
Renamed from deploymentStrategy
tostrategy
.nginx.enabled
gateway.enabled
nginx.extraArgs
gateway.extraArgs
nginx.extraContainers
gateway.extraContainers
nginx.extraEnvFrom
gateway.extraEnvFrom
nginx.extraEnv
gateway.env
Renamed from extraEnv
toenv
.nginx.extraVolumeMounts
gateway.extraVolumeMounts
nginx.extraVolumes
gateway.extraVolumes
nginx.image
gateway.nginx.image
Nested under proxy.nginx
.nginx.ingress
gateway.ingress
nginx.nginxConfig
gateway.nginx.config
Renamed from nginxConfig
toconfig
and nested underproxy.nginx
.nginx.nodeSelector
gateway.nodeSelector
nginx.podAnnotations
gateway.podAnnotations
nginx.podDisruptionBudget
gateway.podDisruptionBudget
nginx.podLabels
gateway.podLabels
nginx.podSecurityContext
gateway.securityContext
Renamed from podSecurityContext
tosecurityContext
.nginx.priorityClassName
gateway.priorityClassName
nginx.readinessProbe
gateway.readinessProbe
nginx.replicas
gateway.replicas
nginx.resources
gateway.resources
nginx.route
gateway.route
nginx.service
gateway.service
nginx.terminationGracePeriodSeconds
gateway.terminationGracePeriodSeconds
nginx.tolerations
gateway.tolerations
nginx.topologySpreadConstraints
gateway.topologySpreadConstraints
nginx.verboseLogging
gateway.nginx.verboseLogging
Nested under proxy.nginx
.Upgrade the Helm release with the migrated values file
custom.yaml
. This concludes the migration.helm upgrade $RELEASE grafana/mimir-distributed -f custom.yaml
Examples
The examples that follow show how your Helm values file changes after migrating from an NGINX setup to a gateway setup.
nginx:
enabled: true
replicas: 4
deploymentStrategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 100%
maxUnavailable: 10%
affinity: |
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchExpressions:
- key: noisyNeighbour
operator: In
values:
- 'true'
topologyKey: 'kubernetes.io/hostname'
extraEnv:
- name: SPECIAL_TYPE_KEY
valueFrom:
configMapKeyRef:
name: special-config
key: SPECIAL_TYPE
basicAuth:
enabled: true
username: user
password: pass
image:
tag: 1.25-alpine
nginxConfig:
logFormat: |-
main '$remote_addr - $remote_user [$time_local] $status '
'"$request" $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
podSecurityContext:
readOnlyRootFilesystem: true
ingress:
enabled: true
hosts:
- host: mimir.example.com
paths:
- path: /
pathType: Prefix
tls:
- secretName: mimir-gateway-tls
hosts:
- mimir.example.com
The Helm values file after finishing the migration:
nginx:
enabled: false
gateway:
enabledNonEnterprise: true
replicas: 4
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 100%
maxUnavailable: 10%
affinity:
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchExpressions:
- key: noisyNeighbour
operator: In
values:
- "true"
topologyKey: "kubernetes.io/hostname"
env:
- name: SPECIAL_TYPE_KEY
valueFrom:
configMapKeyRef:
name: special-config
key: SPECIAL_TYPE
nginx:
basicAuth:
enabled: true
username: user
password: pass
image:
tag: 1.25-alpine
nginxConfig:
logFormat: |-
main '$remote_addr - $remote_user [$time_local] $status '
'"$request" $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
securityContext:
readOnlyRootFilesystem: true
ingress:
enabled: true
nameOverride: mimir-nginx
hosts:
- host: mimir.example.com
paths:
- path: /
pathType: Prefix
tls:
- secretName: mimir-gateway-tls
hosts:
- mimir.example.com