Basic Auth on Kubernetes Ingress

Basic Auth is supported by nearly every major web client, library, and utility.

Posted by Craig Johnston on Saturday, May 19, 2018

Basic Auth is one of the oldest and easiest ways to secure a web page or API endpoint. Basic Auth does not have many features and lacks the sophistication of more modern access controls (see Ingress Nginx Auth Examples). However, Basic Auth is supported by nearly every major web client, library, and utility. Basic Auth is secure, stable and perfect for quick security on Kubernetes projects. Basic Auth can easily we swapped out later as requirements demand or provide a foundation for implementations such as OAuth 2 and JWT.

First, you need an Ingress controller on your Kubernetes cluster and at least one ingress rule that we can apply Basic Auth. If you are following along with my articles on building a Production Hobby Cluster Kubernetes and do not yet have Ingress installed, you should read Ingress on Custom Kubernetes before getting started.


The Basic Auth process sends credentials to the server in the clear, although encrypted and base64’d, they can be quickly reversed back into a human-readable string. Because of this, it is essential we are issuing calls over SSL. However, if the information or service being password protected should be hidden, then SSL encrypted communication would already be required.

For the Production Hobby Cluster we use Let’s Encrypt, so if you have not done so already you can check out my article on setting up Let’s Encrypt for your custom cluster read: Let’s Encrypt, Kubernetes.

Create a User and Password

Start by creating an htpasswd file that contains the Basic Auth credentials. The following creates a user called sysop, choose whatever username you like.

htpasswd -c ./auth sysop

It is important to name the file auth. The filename is used as the key in the key-value pair under the data section of secret.

After entering a password for the new user twice, you end up with the file auth.

Create a Secret

Kubernetes can create a generic Secret from the generated auth file, or from any file, however, the format of the htpasswd generated file is necessary for use with Basic Auth. The file name is used as the key in Basic Auth secret, therefore its best to name it auth and avoid having to edit the secret. Ingress uses the new Secret in it’s annotation section to provide Basic Auth.

The kubectl create secret command can create a secret from a local file, directory or literal value using the generic directive. In the example below I call the new secret sysop, named after the single set of credentials stored in it. However, if you are grouping many credentials, it would be better to give it a more generic name.

Create the Secret:

kubectl create secret generic sysop --from-file auth

Ensure the Secret was created successfully by viewing the details:

kubectl get secret sysop -o yaml

You should have a secret similar to the following:

apiVersion: v1
  auth: c3avb2A2GGFwcjEkMmo5SwoucC4kcWtDR3NTVUxSDXJmTVkwNUwxUlZYLbo=
kind: Secret
  creationTimestamp: 2018-05-18T06:55:51Z
  name: sysop
  namespace: default
  resourceVersion: "265674"
  selfLink: /api/v1/namespaces/default/secrets/sysop
  uid: 2bfb399c-58d6-11e8-b11e-5600017e897a
type: Opaque

Of course, you should avoid publishing your new Secret like I just did, since the auth: value under data: is only a base64 encoded version of the username and encoded password pair. The password may be reversed quickly with a dictionary attack or other password cracking utilities.

Protect Ingress

The following is an example Ingress configuration for a test application called ok running on the test cluster.

 apiVersion: extensions/v1beta1
 kind: Ingress
   name: ok-auth
     app: ok-auth
     system: test
   annotations: basic sysop "Authentication Required - ok"
   - host:
       - backend:
           serviceName: "ok"
           servicePort: 5001
         path: /
   - hosts:
     secretName: la-txn2-net-tls

All that is needed are three Ingress annotations: - basic - sysop - “Authentication Required - ok.”

The Ingress for is now Basic Auth protected using credentials in a Secret called sysop.

Port Forwarding / Local Development

Check out kubefwd for a simple command line utility that bulk forwards services of one or more namespaces to your local workstation.


If you found this article useful, you may want to check out all the articles used to build on the Production Hobby Cluster tagged with

Additional examples of Ingress authentication can be found at the official Ingress Nginx Auth Examples repository.

If in a few days you find yourself setting up a cluster in Japan or Germany on Linode, and another two in Australia and France on vultr, then you may have just joined the PHC (Performance Hobby Clusters) club. Some people tinker late at night on their truck, we benchmark and test the resilience of node failures on our overseas, budget kubernetes clusters. It’s all about going big, on the cheap.

k8s performance hobby clusters

Basic Auth on Kubernetes Ingress: Basic Auth is supported by nearly every major web client, library, and utility. by Craig Johnston is licensed under a Creative Commons Attribution 4.0 International License. Creative Commons License