Deploy

Getting traffic into your cluster

Fury Kubernetes modules are deployed using the furyctl command line tool.

Packages are then customized with kustomize. It lets you create customized Kubernetes resources based on other Kubernetes resource files (bases) using patches or additional resources, leaving the original YAML untouched. To learn how to create you own customization layer with it, please see the kustomize official repository.

Requirements

Compatibility

Module Version / Kubernetes Version 1.14.X 1.15.X 1.16.X 1.17.X 1.18.X
v1.2.0
v1.3.0
v1.4.0
v1.4.1
v1.5.0
v1.6.0
v1.6.1
v1.7.0
  • Compatible
  • Has issues
  • Incompatible

Single vs Dual Controller

As first step, you should choose what type of ingress controller you want to use in your cluster. Fury provides two classes, Single and Dual Ingress Controller.

The Single Controller Package deploys a single class nginx Ingress Controller that serves all the traffic, both internal (private) and external (public) to the cluster.

The Dual Controller Package deploys a dual class nginx Ingress Controller, divided into the internal-ingress and the external-ingress. The internal-ingress class is in charge of serving traffic that is inside the cluster, like users accessing via VPN to internal services, for example application's admin panels or other resources that you don't want to expose to the Internet. The external-ingress serves all the traffic for the applications that are exposed to the outside of the cluster, for example, the frontend application to end users.

nginx Ingress Controller for GKE

This package deploys Ingress Controller for Google Kubernetes Engine, it requires that the nginx package has been installed previously and uses the native GKE LoadBalancer object to expose the Ingress Controller to the Internet.

Default Configuration

For all single, dual and the GKE packages, the Fury Kubernetes Ingress module is deployed with the following default configuration:

  • Maximum allowed size of the client request body: 10m
  • HTTP status code used in redirects: 301
  • Metrics are scraped by Prometheus every 10s

Additionaly, the following Prometheus alerts are setup by default:

Parameter Description Severity Interval
NginxIngressDown This alert fires if Promethes target discovery was not able to reach ingress-nginx-metrics in the last 15 minutes. critical 15m
NginxIngressFailureRate This alert fires if the failure rate (the rate of 5xx reponses) measured on a time window of 2 minutes was higher than 10% in the last 10 minutes. critical 10m
NginxIngressFailedReload This alert fires if the ingress’ configuration reload failed in the last 10 minutes. warning 10m
NginxIngressLatencyTooHigh This alert fires if the ingress 99th percentile latency was more than 5 seconds in the last 10 minutes. warning 10m
NginxIngressLatencyTooHigh This alert fires if the ingress 99th percentile latency was more than 10 seconds in the last 10 minutes. critical 10m
NginxIngressCertificateExpiration This alert fires if the certificate for a given host is expiring in less than 7 days. warning
NginxIngressCertificateExpiration This alert fires if the certificate for a given host is expiring in less than 1 days. critical

Deploying the Ingress Controller

Once you selected the type of ingress you want to deploy (nginx, dual-nginx or nginx-gke) you can download the packages for a given Ingress Module package with the default configuration using one of the following provided Furyfile.yml:

Single Ingress:

bases:
  - name: ingress/nginx
    version: "v1.7.0"

Dual Ingress:

bases:
  - name: ingress/dual-nginx
    version: "v1.7.0"

GKE:

Remember that if you want to deploy the ingress-gke package you need to deploy also the nginx package:

  - name: ingress/nginx
    version: "v1.7.0"
  - name: ingress/nginx-gke
    version: "v1.7.0"

once you have the Furyfile.yml ready, then execute

$ furyctl vendor

to download the packages under ./vendor/katalog/ingress/<chosen-ingress-package>.

See furyctl documentation for mode details.

To deploy the packages to your cluster, define a kustomization.yaml with the following content:

bases:
- ./vendor/katalog/ingress/<chosen-ingress-package>

and execute the following command to deploy the Fury Kubernetes Ingress module package:

$ kustomize build . | kubectl apply -f -

See kustomize documentation for details about kustomization.yaml format.

cert-manager

Fury Kubernetes Ingress cert-manager package is the defacto tool to manage certificates in Kubernetes. It manages the issuing and automatic updates of certificates for the domains served by the Ingress Controller.

The package's default configuration includes:

  • ClusterIssuer as the default issuer kind
  • Let's Encrypt as the default issuer, both staging and production.

To deploy the cert-manager package, add the package to your bases inside the Furyfile.yml, for example, like this:

bases:
  - name: ingress/dual-nginx
    version: "v1.7.0"
  - name: ingress/cert-manager
    version: "v1.7.0"

then execute

$ furyctl vendor

to download the packages under ./vendor/katalog/ingress/cert-manager.

See furyctl documentation for mode details.

To deploy the package to your cluster, define a kustomization.yaml with the following content:

bases:
- ./vendor/katalog/ingress/cert-manager

Depending of nginx or dual-nginx you need to specify the class name accordingly. To do that, you need to patch the ClusterIssuer resource in order to keep it synced with your specific deployment. So before proceeding to the build and apply, you should provide a patchesJson6902 like the following:

---
patchesJson6902:
    - target:
          group: certmanager.k8s.io
          version: v1alpha1
          kind: ClusterIssuer
          name: letsencrypt-staging
      path: patches/dual-nginx.yml
    - target:
          group: certmanager.k8s.io
          version: v1alpha1
          kind: ClusterIssuer
          name: letsencrypt-prod
      path: patches/dual-nginx.yml

and under the patches/dual-nginx.yml:

---
- op: "replace"
  path: "/spec/acme/solvers/0/http01/ingress/class"
  value: "external"

this is only needed when you use the the dual-nginx because the default is the nginx single node

Finally execute the following command to deploy the Fury Kubernetes Ingress module package:

$ kustomize build . | kubectl apply -f -

See kustomize documentation for details about kustomization.yaml format.

Forecastle

Forecastle provides the following set of features:

  • List apps found in all namespaces listed in the configmap
  • Search apps
  • Grouped apps per namespace
  • Configurable header (Title and colors)
  • Multiple instance support
  • Provide Custom apps
  • CRD ForecastleApp for adding custom apps
  • Custom groups and URLs for the apps
  • Details per app

To deploy the forecastle package, add the package to your bases inside the Furyfile.yml, for example, like this:

bases:
  - name: ingress/dual-nginx
    version: "v1.7.0"
  - name: ingress/cert-manager
    version: "v1.7.0"
  - name: ingress/forecastle
    version: "v1.7.0"

then execute

$ furyctl vendor

to download the packages under ./vendor/katalog/ingress/forecastle.

See furyctl documentation for mode details.

To deploy the package to your cluster, define a kustomization.yaml with the following content:

bases:
- ./vendor/katalog/ingress/forecastle

and execute the following command to deploy the Fury Kubernetes Ingress module package:

$ kustomize build . | kubectl apply -f -

See kustomize documentation for details about kustomization.yaml format.

Basic usage

Forecastle looks for a specific annotations on ingresses.

Add the following annotations to your ingresses in order to be discovered by Forecastle:

Annotation Description Required
forecastle.stakater.com/expose Add this with value true to the ingress of the app you want to show in Forecastle true
forecastle.stakater.com/icon Icon/Image URL of the application; An icons/logos/images collection repo Icons false
forecastle.stakater.com/appName A custom name for your application. Use if you don't want to use name of the ingress ßßß false
forecastle.stakater.com/group A custom group name. Use if you want the application to show in a different group than the namespace it is running in false
forecastle.stakater.com/instance A comma separated list of name/s of the forecastle instance/s where you want this application to appear. Use when you have multiple forecastle dashboards false
forecastle.stakater.com/url A URL for the forecastle app (This will override the ingress URL). It MUST begin with a scheme i.e., http:// or https:// false
forecastle.stakater.com/properties A comma separate list of key value pairs for the properties. This will appear as an expandable list for the app false
forecastle.stakater.com/network-restricted Specify whether the app is network restricted or not (true or false) false

See Forecastle official repository for more details.

LDAP Authentication

nginx LDAP Authentication provides LDAP based HTTP basic authentication to the traffic served by the Ingress Controller.

The package is deployed with following default configuration:

  • POD runs unprivileged
  • POD with limited hardened RBAC configuration
  • POD with limited resources

To deploy the LDAP Authentication package, add the base to your Furyfile.yml:

bases:
  - name: ingress/nginx-ldap-auth
    version: "v1.7.0"

then execute

$ furyctl vendor

to download the packages under ./vendor/katalog/ingress/nginx-ldap-auth.

See furyctl documentation for mode details.

To deploy the package to your cluster, define a kustomization.yaml with the following content:

bases:
- ./vendor/katalog/ingress/nginx-ldap-auth/config
- ./vendor/katalog/ingress/nginx-ldap-auth

Before applying the kustomization, the nginx LDAP Authenticatoin package needs a kubernetes secret named nginx-ldap-auth with a config.yaml key. An example is available under the package's repo config directory.

$ kustomize build katalog/nginx-ldap-auth/config/
apiVersion: v1
data:
  config.yaml: d2ViOiAwLjAuMC4wOjU1NTUKcGF0aDogLwpzZXJ2ZXJzOgogIC0gbGRhcDovL2xkYXAtc2VydmVyCmF1dGg6CiAgYmluZEROOiBjbj1hZG1pbixkYz1zaWdodXAsZGM9aW8KICBiaW5kUFc6IEhhdEZyaWRheQp1c2VyOgogIGJhc2VETjogb3U9Z3JvdXAtYSxvdT1zeXN0ZW0sZGM9c2lnaHVwLGRjPWlvCiAgZmlsdGVyOiAiKGNuPXswfSkiCg==
kind: Secret
metadata:
  name: nginx-ldap-auth
  namespace: ingress-nginx
type: Opaque

Note that config.yaml property is a file with the LDAP configuration:

web: 0.0.0.0:5555
path: /
servers:
  - ldap://ldap-server
auth:
  bindDN: cn=admin,dc=sighup,dc=io
  bindPW: HatFriday
user:
  baseDN: ou=group-a,ou=system,dc=sighup,dc=io
  filter: "(cn={0})"

To know all available configuration options please refere to the upstream project at github.

More configuration examples under tests/nginx-ldap-auth including one example filtering users by LDAP groups:

web: 0.0.0.0:5555
path: /
servers:
  - ldap://ldap-server.demo-ldap.svc.cluster.local
auth:
  bindDN: cn=admin,dc=sighup,dc=io
  bindPW: HatFriday
user:
  baseDN: ou=people,dc=sighup,dc=io
  filter: "(cn={0})"
  requiredGroups:
  - amministrazione
  - engineering
group:
  baseDN: ou=groups,dc=sighup,dc=io
  groupAttr: cn
  filter: "(member={0})"

Finally, execute the following command to deploy the Fury Kubernetes Ingress module package:

$ kustomize build . | kubectl apply -f -

See kustomize documentation for details about kustomization.yaml format.

Usage

Once deployed, any ingress definition can be configured to be protected by HTTP basic access authentication against LDAP:

kubectl annotate ingress YOUR_INGRESS "nginx.ingress.kubernetes.io/auth-url=http://nginx-ldap-auth.ingress-nginx.svc.cluster.local" --overwrite

Important notice

Be aware this authentication method is transmitted in every request by your browser in plain text, so you should be using HTTPS.


Last modified 25.06.2020: Updating module references (82f9ca7)