{"id":13337962,"url":"https://github.com/anderseknert/nginx-tls-terminator","last_synced_at":"2025-09-16T12:45:15.526Z","repository":{"id":44995381,"uuid":"278738774","full_name":"anderseknert/nginx-tls-terminator","owner":"anderseknert","description":"TLS terminating nginx proxy for kubernetes","archived":false,"fork":false,"pushed_at":"2022-01-14T22:17:09.000Z","size":86,"stargazers_count":10,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-10T07:13:10.331Z","etag":null,"topics":["https","kubernetes","nginx","nginx-tls-terminator","openssl","proxy","sidecar","sidecar-container","sidecar-proxy","ssl","ssl-termination","tls","tls-certificate","tls-proxy","tls-termination"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anderseknert.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-10T21:42:42.000Z","updated_at":"2024-06-27T11:11:50.000Z","dependencies_parsed_at":"2022-09-23T18:41:29.191Z","dependency_job_id":null,"html_url":"https://github.com/anderseknert/nginx-tls-terminator","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anderseknert%2Fnginx-tls-terminator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anderseknert%2Fnginx-tls-terminator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anderseknert%2Fnginx-tls-terminator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anderseknert%2Fnginx-tls-terminator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anderseknert","download_url":"https://codeload.github.com/anderseknert/nginx-tls-terminator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248386369,"owners_count":21095066,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["https","kubernetes","nginx","nginx-tls-terminator","openssl","proxy","sidecar","sidecar-container","sidecar-proxy","ssl","ssl-termination","tls","tls-certificate","tls-proxy","tls-termination"],"created_at":"2024-07-29T19:15:16.516Z","updated_at":"2025-09-16T12:45:10.502Z","avatar_url":"https://github.com/anderseknert.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nginx-tls-terminator\n\n![build](https://github.com/anderseknert/nginx-tls-terminator/workflows/build/badge.svg)\n\n**Single-purpose TLS terminating nginx proxy.**\n\nPrimary function is to run as a sidecar container in kubernetes pods where the app running in the main container either does not support TLS, or it's inconvenient to add it - such as for legacy apps or where the code is not under your control. Another common use case is when external traffic has TLS terminated by the ingress controller, but some internal services need to reach the same services from the inside on the same URL. One example of this is the issuer URL provided in OAuth2 and OpenID Connect, where both external and internal applications will need to query the same endpoints over a secure channel.\n\n**Features:**\n* Small single-purpose container at ~9 MB with minimal configuration needed.\n* Does not require root privileges and runs as non-root user by default. Runs with strictest `securityContext` configured on the container.\n* Running with a read-only root filesystem as easy as mounting a volume on `/tmp`.\n* Exposed TLS port as well as target upstream port configurable through environment variables.\n\n## Configuration options\n\n| Option              | Default               | Description                                                                                     |\n|---------------------|-----------------------|-------------------------------------------------------------------------------------------------|\n| PROXY_LISTEN_PORT   | 8443                  | Port to listen to for incoming HTTPS requests.                                                  |\n| PROXY_UPSTREAM_PORT | 8080                  | Port to forward HTTP traffic to within pod.                                                     |\n| ACCESS_LOG_LOCATION | /tmp/nginx.access.log | Location of access log. Use /dev/stdout to log to console, or /dev/null to discard access logs. |\n\n## Usage instructions\n\n### Obtaining a certificate\n\nThe first step to enable TLS for your service is to obtain a certificate. This can be done in a number of ways, such as:\n\n* Using an established certificate authority, such as [Let's Encrypt](https://letsencrypt.org/).\n* Generating a self-signed certificate (for testing).\n\nMore info on obtaining a certificate for use in kubernetes can be found in the [kubernetes docs](https://kubernetes.io/docs/tasks/tls/managing-tls-in-a-cluster/).\n\n### Storing the certificate\n\nOnce a certificate has been obtained, you'll need to store it somewhere where the nginx-tls-terminatr can find it - normally a [kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/). The secret consists of the certificate (`tls.crt`) and a signing key (`tls.key`) and is easily created with kubectl.\n\n```shell\nkubectl create secret tls tls-terminator-cert \\\n        --cert=path/to/cert/tls.crt \\\n        --key=path/to/cert/tls.key\n```\n\n### Adding the nginx-tls-terminator sidecar container\n\nWe'll now need to edit the deployment responsible for the pod you'll want to patch with TLS terminating capabilities. Given an example deployment like this:\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: my-awesome-app\n  labels:\n    app: my-awesome-app\nspec:\n  selector:\n    matchLabels:\n      app: my-awesome-app\n  template:\n    metadata:\n      labels:\n        app: my-awesome-app\n    spec:\n      volumes:\n      - name: tls-terminator-cert\n        secret:\n          secretName: tls-terminator-cert\n      - name: tmp\n        emptyDir: {}\n      containers:\n      - name: my-awesome-app-container\n        image: my-awesome-app:1.2.3\n        ports:\n        - containerPort: 80\n```\n\nWe will patch the pod spec to both mount the secret we created and of course inject our TLS terminating sidecar container. First, let's add the secret to our pod spec (under `spec.template.spec`):\n\n```yaml\nvolumes:\n- name: tls-terminator-cert\n  secret:\n    secretName: tls-terminator-cert\n```\nThen, add the nginx-tls-terminator sidecar container mounting the secret volume created above (under `spec.template.spec.containers`):\n\n```yaml\n- name: nginx-tls-terminator\n  image: eknert/nginx-tls-terminator:1.0.1\n  ports:\n  - containerPort: 8443\n  volumeMounts:\n  - mountPath: /etc/nginx/ssl\n    name: tls-terminator-cert\n    readOnly: true\n  - mountPath: /tmp\n    name: tmp\n  securityContext:\n    allowPrivilegeEscalation: false\n    runAsNonRoot: true\n    runAsUser: 2000\n    runAsGroup: 2000\n    readOnlyRootFilesystem: true\n    capabilities:\n      drop:\n      - all\n  env:\n  - name: PROXY_LISTEN_PORT\n    value: \"1234\" # OPTIONAL: Defaults to 8443\n  - name: PROXY_UPSTREAM_PORT\n    value: \"80\"   # OPTIONAL: Default to 8080\n```\n\nFor all available versions/tags, see [Docker Hub](https://hub.docker.com/r/eknert/nginx-tls-terminator).\n\n### Kustomize\n\nRepeating the above steps for multiple deployments is bound to be time consuming. We can both structure and simplify the process with the help of [kustomize](https://kustomize.io/). An example kustomization file to create both config, secrets and the actual sidecar overlay could look something like below:\n\n```yaml\napiVersion: kustomize.config.k8s.io/v1beta1\nkind: Kustomization\n\n# Point to deployment to be patched with the TLS terminating sidecar\nresources:\n- deployment.yaml\n\nconfigMapGenerator:\n- name: tls-terminator-conf\n  behavior: create\n  literals:\n  - PROXY_LISTEN_PORT=8443\n  - PROXY_UPSTREAM_PORT=80\n\nsecretGenerator:\n- name: tls-terminator-cert\n  files:\n  - cert/tls.crt\n  - cert/tls.key\n  type: kubernetes.io/tls\n\npatchesStrategicMerge:\n- volume.yaml\n- sidecar.yaml\n```\n\nPatching the deployment with the sidecar and any other needed resources is now as easy as:\n\n```shell\n$ kubectl apply -k kustomize/\nconfigmap/tls-terminator-conf-d8f8ffgbg7 created\nsecret/tls-terminator-cert-76bkgtmk95 created\ndeployment.apps/my-awesome-app created\n```\n\nSee the [kustomize](kustomize/) directory for the full example.\n\n### Configuring service\n\nThe TLS terminating sidecar container should now be up and running, proxying TLS encrypted requests on port 8443 to port 80 on the main container. As the pods are normally exposed through a kubernetes service, we'll need to make it route traffic to our sidecar container for TLS traffic. Given an existing service looking something like this:\n\n```yaml\napiVersion: v1\nkind: Service\nmetadata:\n  labels:\n    app: my-awesome-app\nspec:\n  clusterIP: 10.108.119.63\n  ports:\n  - name: http\n    port: 80\n    protocol: TCP\n    targetPort: 80\n  selector:\n    app: my-awesome-app\n```\n\nAll we'll need to do is to add handling to the port we configured for our sidecar (8443) - we'll also normally want to expose this on the regular HTTPS port, 443:\n\n```yaml\n- name: https\n  port: 443\n  protocol: TCP\n  targetPort: 8443\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanderseknert%2Fnginx-tls-terminator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanderseknert%2Fnginx-tls-terminator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanderseknert%2Fnginx-tls-terminator/lists"}