Lessons Learned - Configuring an Nginx K8S Ingress Using Annotations

This post was initially published on 6/5/2020

I recently installed my first Nextcloud server on top of a new Digital Ocean Kubernetes (K8S) cluster as a Kubernetes training exercise. I ended up learning a ton about Kubernetes but I also learned a lot about how to run a Nextcloud server.

One thing I learned very quickly is that most default web server configurations don't support uploading files larger than a few megabytes. I therefore got a ton of errors the first time I tried syncing an image folder.

Since I was using the official nextcloud:apache image I figured that the built-in Apache server was configured properly. I therefore started looking into how I could configure my Kubernetes Ingress to accept large file uploads. And since I was using the Nginx Ingress Controller it had to be Nginx-specific.

The docs were a little confusing on this, but the good news is that all I had to do was set an annotation in the ingress like this:

  apiVersion: extensions/v1beta1
  kind: Ingress
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
      kubernetes.io/ingress.class: "nginx"
      # maps to client_max_body_size
      nginx.ingress.kubernetes.io/proxy-body-size: 128m
    name: nextcloud-ingress
      - hosts:
          - docs.tompurl.com
        secretName: nextcloud-cert-tls
      - host: docs.tompurl.com
            - backend:
                serviceName: nextcloud
                servicePort: 80

The key line is this one:

  • nginx.ingress.kubernetes.io/proxy-body-size: 128m

My understanding is that this line configures the client_max_body_size variable in your Ingress' nginx.conf file. Granted, it would be nice if the annotation had a name that is closer to the conf file variable name, but I'm just glad I figured this out ๐Ÿ˜ผ

One of the killer features of using Nginx as your Kubernetes Ingress Controller is that you can configure tons of different things using simple annotations. You can find more information on them here:

  • https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/