Move all documentation under docs/
This commit is contained in:
Aarni Koskela
parent
959d7b1056
commit
0aa9d2e89f
8 changed files with 485 additions and 480 deletions
322
deploy/README.md
322
deploy/README.md
|
|
@ -1,321 +1,3 @@
|
|||
# Installation Guide
|
||||
# Deployment documentation moved!
|
||||
|
||||
## Contents
|
||||
|
||||
- [Mandatory commands](#mandatory-commands)
|
||||
- [Install without RBAC roles](#install-without-rbac-roles)
|
||||
- [Install with RBAC roles](#install-with-rbac-roles)
|
||||
- [Custom Provider](#custom-provider)
|
||||
- [Docker for Mac](#docker-for-mac)
|
||||
- [minikube](#minikube)
|
||||
- [AWS](#aws)
|
||||
- [GCE - GKE](#gce---gke)
|
||||
- [Azure](#azure)
|
||||
- [Baremetal](#baremetal)
|
||||
- [Using Helm](#using-helm)
|
||||
- [Verify installation](#verify-installation)
|
||||
- [Detect installed version](#detect-installed-version)
|
||||
- [Deploying the config-map](#deploying-the-config-map)
|
||||
|
||||
## Generic Deployment
|
||||
|
||||
The following resources are required for a generic deployment.
|
||||
|
||||
### Mandatory commands
|
||||
|
||||
```console
|
||||
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/namespace.yaml \
|
||||
| kubectl apply -f -
|
||||
|
||||
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/default-backend.yaml \
|
||||
| kubectl apply -f -
|
||||
|
||||
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/configmap.yaml \
|
||||
| kubectl apply -f -
|
||||
|
||||
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/tcp-services-configmap.yaml \
|
||||
| kubectl apply -f -
|
||||
|
||||
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/udp-services-configmap.yaml \
|
||||
| kubectl apply -f -
|
||||
```
|
||||
|
||||
### Install without RBAC roles
|
||||
|
||||
```console
|
||||
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/without-rbac.yaml \
|
||||
| kubectl apply -f -
|
||||
```
|
||||
|
||||
### Install with RBAC roles
|
||||
|
||||
Please check the [RBAC](rbac.md) document.
|
||||
|
||||
```console
|
||||
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/rbac.yaml \
|
||||
| kubectl apply -f -
|
||||
|
||||
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/with-rbac.yaml \
|
||||
| kubectl apply -f -
|
||||
```
|
||||
|
||||
## Custom Service Provider Deployment
|
||||
|
||||
There are cloud provider specific yaml files.
|
||||
|
||||
### Docker for Mac
|
||||
|
||||
Kubernetes is available for Docker for Mac's Edge channel. Switch to the [Edge
|
||||
channel][edge] and [enable Kubernetes][enable].
|
||||
|
||||
[edge]: https://docs.docker.com/docker-for-mac/install/
|
||||
[enable]: https://docs.docker.com/docker-for-mac/#kubernetes
|
||||
|
||||
Patch the nginx ingress controller deployment to add the flag `--publish-service`
|
||||
|
||||
```console
|
||||
kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \
|
||||
--patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)"
|
||||
```
|
||||
|
||||
Create a service
|
||||
|
||||
```console
|
||||
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/docker-for-mac/service.yaml \
|
||||
| kubectl apply -f -
|
||||
```
|
||||
|
||||
### minikube
|
||||
|
||||
For standard usage:
|
||||
|
||||
```console
|
||||
minikube addons enable ingress
|
||||
```
|
||||
|
||||
For development:
|
||||
|
||||
1. Disable the ingress addon:
|
||||
|
||||
```console
|
||||
$ minikube addons disable ingress
|
||||
```
|
||||
|
||||
2. Use the [docker daemon](https://github.com/kubernetes/minikube/blob/master/docs/reusing_the_docker_daemon.md)
|
||||
3. [Build the image](../docs/development.md)
|
||||
4. Perform [Mandatory commands](#mandatory-commands)
|
||||
5. Install the `nginx-ingress-controller` deployment [without RBAC roles](#install-without-rbac-roles) or [with RBAC roles](#install-with-rbac-roles)
|
||||
6. Edit the `nginx-ingress-controller` deployment to use your custom image. Local images can be seen by performing `docker images`.
|
||||
|
||||
```console
|
||||
$ kubectl edit deployment nginx-ingress-controller -n ingress-nginx
|
||||
```
|
||||
|
||||
edit the following section:
|
||||
|
||||
```yaml
|
||||
image: <IMAGE-NAME>:<TAG>
|
||||
imagePullPolicy: IfNotPresent
|
||||
name: nginx-ingress-controller
|
||||
```
|
||||
|
||||
7. Confirm the `nginx-ingress-controller` deployment exists:
|
||||
|
||||
```console
|
||||
$ kubectl get pods -n ingress-nginx
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
default-http-backend-66b447d9cf-rrlf9 1/1 Running 0 12s
|
||||
nginx-ingress-controller-fdcdcd6dd-vvpgs 1/1 Running 0 11s
|
||||
```
|
||||
|
||||
### AWS
|
||||
|
||||
In AWS we use an Elastic Load Balancer (ELB) to expose the NGINX Ingress controller behind a Service of `Type=LoadBalancer`.
|
||||
Since Kubernetes v1.9.0 it is possible to use a classic load balancer (ELB) or network load balancer (NLB)
|
||||
Please check the [elastic load balancing AWS details page](https://aws.amazon.com/es/elasticloadbalancing/details/)
|
||||
|
||||
#### Elastic Load Balancer - ELB
|
||||
|
||||
This setup requires to choose in which layer (L4 or L7) we want to configure the ELB:
|
||||
|
||||
- [Layer 4](https://en.wikipedia.org/wiki/OSI_model#Layer_4:_Transport_Layer): use TCP as the listener protocol for ports 80 and 443.
|
||||
- [Layer 7](https://en.wikipedia.org/wiki/OSI_model#Layer_7:_Application_Layer): use HTTP as the listener protocol for port 80 and terminate TLS in the ELB
|
||||
|
||||
Patch the nginx ingress controller deployment to add the flag `--publish-service`
|
||||
|
||||
```console
|
||||
kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \
|
||||
--patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)"
|
||||
```
|
||||
|
||||
For L4:
|
||||
|
||||
```console
|
||||
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-l4.yaml
|
||||
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/patch-configmap-l4.yaml
|
||||
```
|
||||
|
||||
For L7:
|
||||
|
||||
Change line of the file `provider/aws/service-l7.yaml` replacing the dummy id with a valid one `"arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX"`
|
||||
Then execute:
|
||||
|
||||
```console
|
||||
kubectl apply -f provider/aws/service-l7.yaml
|
||||
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/patch-configmap-l7.yaml
|
||||
```
|
||||
|
||||
This example creates an ELB with just two listeners, one in port 80 and another in port 443
|
||||
|
||||
|
||||
|
||||
If the ingress controller uses RBAC run:
|
||||
|
||||
```console
|
||||
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml
|
||||
```
|
||||
|
||||
If not run:
|
||||
|
||||
```console
|
||||
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml
|
||||
```
|
||||
|
||||
#### Network Load Balancer (NLB)
|
||||
|
||||
This type of load balancer is supported since v1.10.0 as an ALPHA feature.
|
||||
|
||||
```console
|
||||
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-nlb.yaml
|
||||
```
|
||||
|
||||
If the ingress controller uses RBAC run:
|
||||
|
||||
```console
|
||||
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml
|
||||
```
|
||||
|
||||
If not run:
|
||||
|
||||
```console
|
||||
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml
|
||||
```
|
||||
|
||||
### GCE - GKE
|
||||
|
||||
Patch the nginx ingress controller deployment to add the flag `--publish-service`
|
||||
|
||||
```console
|
||||
kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \
|
||||
--patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)"
|
||||
```
|
||||
|
||||
```console
|
||||
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/gce-gke/service.yaml \
|
||||
| kubectl apply -f -
|
||||
```
|
||||
|
||||
If the ingress controller uses RBAC run:
|
||||
|
||||
```console
|
||||
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml | kubectl apply -f -
|
||||
```
|
||||
|
||||
If not run:
|
||||
|
||||
```console
|
||||
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml | kubectl apply -f -
|
||||
```
|
||||
|
||||
**Important Note:** proxy protocol is not supported in GCE/GKE
|
||||
|
||||
### Azure
|
||||
|
||||
Patch the nginx ingress controller deployment to add the flag `--publish-service`
|
||||
|
||||
```console
|
||||
kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \
|
||||
--patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)"
|
||||
```
|
||||
|
||||
```console
|
||||
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/azure/service.yaml \
|
||||
| kubectl apply -f -
|
||||
```
|
||||
|
||||
If the ingress controller uses RBAC run:
|
||||
|
||||
```console
|
||||
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml
|
||||
```
|
||||
|
||||
If not run:
|
||||
|
||||
```console
|
||||
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml
|
||||
```
|
||||
|
||||
**Important Note:** proxy protocol is not supported in GCE/GKE
|
||||
|
||||
### Baremetal
|
||||
|
||||
Using [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport):
|
||||
|
||||
```console
|
||||
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/baremetal/service-nodeport.yaml \
|
||||
| kubectl apply -f -
|
||||
```
|
||||
|
||||
## Using Helm
|
||||
|
||||
NGINX Ingress controller can be installed via [Helm](https://helm.sh/) using the chart [stable/nginx](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress) from the official charts repository.
|
||||
To install the chart with the release name `my-nginx`:
|
||||
|
||||
```console
|
||||
helm install stable/nginx-ingress --name my-nginx
|
||||
```
|
||||
|
||||
If the kubernetes cluster has RBAC enabled, then run:
|
||||
|
||||
```console
|
||||
helm install stable/nginx-ingress --name my-nginx --set rbac.create=true
|
||||
```
|
||||
|
||||
## Verify installation
|
||||
|
||||
To check if the ingress controller pods have started, run the following command:
|
||||
|
||||
```console
|
||||
kubectl get pods --all-namespaces -l app=ingress-nginx --watch
|
||||
```
|
||||
|
||||
Once the operator pods are running, you can cancel the above command by typing `Ctrl+C`.
|
||||
Now, you are ready to create your first ingress.
|
||||
|
||||
## Detect installed version
|
||||
|
||||
To detect which version of the ingress controller is running, exec into the pod and run `nginx-ingress-controller version` command.
|
||||
|
||||
```console
|
||||
POD_NAMESPACE=ingress-nginx
|
||||
POD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app=ingress-nginx -o jsonpath={.items[0].metadata.name})
|
||||
kubectl exec -it $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version
|
||||
```
|
||||
|
||||
## Deploying the config-map
|
||||
|
||||
A config map can be used to configure system components for the nginx-controller. In order to begin using a config-map
|
||||
make sure it has been created and is being used in the deployment.
|
||||
|
||||
It is created as seen in the [Mandatory Commands](#mandatory-commands) section above.
|
||||
```console
|
||||
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/configmap.yaml \
|
||||
| kubectl apply -f -
|
||||
```
|
||||
|
||||
and is setup to be used in the deployment [without-rbac](without-rbac.yaml) or [with-rbac](with-rbac.yaml) with the following line:
|
||||
```yaml
|
||||
- --configmap=$(POD_NAMESPACE)/nginx-configuration
|
||||
```
|
||||
|
||||
For information on using the config-map, see its [user-guide](../docs/user-guide/configmap.md).
|
||||
See (/docs/deploy.md)[../docs/deploy.md].
|
||||
|
|
@ -1,76 +0,0 @@
|
|||
# Role Based Access Control - RBAC
|
||||
|
||||
## Overview
|
||||
|
||||
This example applies to nginx-ingress-controllers being deployed in an environment with RBAC enabled.
|
||||
|
||||
Role Based Access Control is comprised of four layers:
|
||||
|
||||
1. `ClusterRole` - permissions assigned to a role that apply to an entire cluster
|
||||
2. `ClusterRoleBinding` - binding a ClusterRole to a specific account
|
||||
3. `Role` - permissions assigned to a role that apply to a specific namespace
|
||||
4. `RoleBinding` - binding a Role to a specific account
|
||||
|
||||
In order for RBAC to be applied to an nginx-ingress-controller, that controller
|
||||
should be assigned to a `ServiceAccount`. That `ServiceAccount` should be
|
||||
bound to the `Role`s and `ClusterRole`s defined for the nginx-ingress-controller.
|
||||
|
||||
## Service Accounts created in this example
|
||||
|
||||
One ServiceAccount is created in this example, `nginx-ingress-serviceaccount`.
|
||||
|
||||
## Permissions Granted in this example
|
||||
|
||||
There are two sets of permissions defined in this example. Cluster-wide
|
||||
permissions defined by the `ClusterRole` named `nginx-ingress-clusterrole`, and
|
||||
namespace specific permissions defined by the `Role` named `nginx-ingress-role`.
|
||||
|
||||
### Cluster Permissions
|
||||
|
||||
These permissions are granted in order for the nginx-ingress-controller to be
|
||||
able to function as an ingress across the cluster. These permissions are
|
||||
granted to the ClusterRole named `nginx-ingress-clusterrole`
|
||||
|
||||
* `configmaps`, `endpoints`, `nodes`, `pods`, `secrets`: list, watch
|
||||
* `nodes`: get
|
||||
* `services`, `ingresses`: get, list, watch
|
||||
* `events`: create, patch
|
||||
* `ingresses/status`: update
|
||||
|
||||
### Namespace Permissions
|
||||
|
||||
These permissions are granted specific to the nginx-ingress namespace. These
|
||||
permissions are granted to the Role named `nginx-ingress-role`
|
||||
|
||||
* `configmaps`, `pods`, `secrets`: get
|
||||
* `endpoints`: get
|
||||
|
||||
Furthermore to support leader-election, the nginx-ingress-controller needs to
|
||||
have access to a `configmap` using the resourceName `ingress-controller-leader-nginx`
|
||||
|
||||
> Note that resourceNames can NOT be used to limit requests using the “create”
|
||||
> verb because authorizers only have access to information that can be obtained
|
||||
> from the request URL, method, and headers (resource names in a “create” request
|
||||
> are part of the request body).
|
||||
|
||||
* `configmaps`: get, update (for resourceName `ingress-controller-leader-nginx`)
|
||||
* `configmaps`: create
|
||||
|
||||
This resourceName is the concatenation of the `election-id` and the
|
||||
`ingress-class` as defined by the ingress-controller, which defaults to:
|
||||
|
||||
* `election-id`: `ingress-controller-leader`
|
||||
* `ingress-class`: `nginx`
|
||||
* `resourceName` : `<election-id>-<ingress-class>`
|
||||
|
||||
Please adapt accordingly if you overwrite either parameter when launching the
|
||||
nginx-ingress-controller.
|
||||
|
||||
### Bindings
|
||||
|
||||
The ServiceAccount `nginx-ingress-serviceaccount` is bound to the Role
|
||||
`nginx-ingress-role` and the ClusterRole `nginx-ingress-clusterrole`.
|
||||
|
||||
The serviceAccountName associated with the containers in the deployment must
|
||||
match the serviceAccount. The namespace references in the Deployment metadata,
|
||||
container arguments, and POD_NAMESPACE should be in the nginx-ingress namespace.
|
||||
Loading…
Add table
Add a link
Reference in a new issue