# Install NGINX Ingress Controller LTS with Manifests




This guide explains how to use Manifests to install F5 NGINX Ingress Controller LTS, then create both common and custom resources and set up role-based access control.

## Before you begin

If you are using NGINX Plus, get the NGINX Ingress Controller LTS JWT and [create a license secret](/nic/lts/install/license-secret.md).

### Get the NGINX Controller Image

**note:**  We recommend installing the latest LTS patch release of NGINX Ingress Controller LTS, available on the GitHub repository's [releases page](https://github.com/nginx/kubernetes-ingress/releases). 

Choose one of the following methods to get the NGINX Ingress Controller LTS image:

- **NGINX Plus Ingress Controller**: You have two options for this, both requiring an NGINX Ingress Controller LTS subscription.
- - [Download NGINX Ingress Controller LTS from the F5 Registry](/nic/lts/install/images/registry-download.md) topic.
- - [Add an NGINX Ingress Controller LTS image to your cluster](/nic/lts/install/images/add-image-to-cluster.md)

### Clone the repository

Clone the NGINX Ingress Controller LTS repository using the command shown below, and replace `<version_number>` with the specific release you want to use.

```shell
git clone https://github.com/nginx/kubernetes-ingress.git --branch <version_number>
```

For example, if you want to use version , the command would be:

```shell
git clone https://github.com/nginx/kubernetes-ingress.git --branch v
```

This guide assumes you are using the latest release.

Change the active directory.

```shell
cd kubernetes-ingress
```

## Set up role-based access control (RBAC) {#configure-rbac}

**Note:** To complete these steps you need admin access to your cluster. Refer to to your Kubernetes platform's documentation to set up admin access. For Google Kubernetes Engine (GKE), you can refer to their [Role-Based Access Control guide](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control).

1. Create a namespace and a service account:

    ```shell
    kubectl apply -f deployments/common/ns-and-sa.yaml
    ```

2. Create a cluster role and binding for the service account:

    ```shell
    kubectl apply -f deployments/rbac/rbac.yaml
    ```

<br>

If you're planning to use F5 WAF for NGINX or F5 DoS for NGINX, additional roles and bindings are needed.

1. (F5 WAF for NGINX only) Create the *App Protect* role and binding:

    ```shell
    kubectl apply -f deployments/rbac/ap-rbac.yaml
    ```

2. (F5 DoS for NGINX only) Create the *App Protect DoS* role and binding:

    ```shell
    kubectl apply -f deployments/rbac/apdos-rbac.yaml
    ```

## Create common resources {#create-common-resources}

In this section, you'll create resources that most NGINX Ingress Controller installations require:

1. (Optional) Create a secret for the default NGINX server's TLS certificate and key. Complete this step only if you're using the [default server TLS secret](/nic/configuration/global-configuration/command-line-arguments#cmdoption-default-server-tls-secret.md) command-line argument. If you're not, feel free to skip this step.

    By default, the server returns a _404 Not Found_ page for all requests when no ingress rules are set up. Although we provide a self-signed certificate and key for testing purposes, we recommend using your own certificate.

    ```shell
    make secrets
    kubectl apply -f examples/shared-examples/default-server-secret/default-server-secret.yaml
    ```

2. Create a ConfigMap to customize your NGINX settings:

    ```shell
    kubectl apply -f deployments/common/nginx-config.yaml
    ```

3. Create an `IngressClass` resource. NGINX Ingress Controller won't start without an `IngressClass` resource.

    ```shell
    kubectl apply -f deployments/common/ingress-class.yaml
    ```

    If you want to make this NGINX Ingress Controller instance your cluster's default, uncomment the `ingressclass.kubernetes.io/is-default-class` annotation. This action will auto-assign `IngressClass` to new ingresses that don't specify an `ingressClassName`.

## Deploy NGINX Ingress Controller LTS {#deploy-ingress-controller}

You have three options for deploying NGINX Ingress Controller LTS:

- **Deployment**. Choose this method for the flexibility to dynamically change the number of NGINX Ingress Controller LTS replicas.
- **DaemonSet**. Choose this method if you want NGINX Ingress Controller LTS to run on all nodes or a subset of nodes.
- **StatefulSet**. Choose this method when you need stable, persistent storage and ordered deployment/scaling for your NGINX Ingress Controller LTS pods.

Before you start, update the [command-line arguments](/nic/lts/configuration/global-configuration/command-line-arguments.md) for the NGINX Ingress Controller LTS container in the relevant manifest file to meet your specific requirements.

### Using a Deployment

For additional context on managing containers using Kubernetes Deployments, refer to the official Kubernetes [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) documentation.

When you deploy NGINX Ingress Controller as a Deployment, Kubernetes automatically sets up a single NGINX Ingress Controller pod.

- For NGINX, run:

    ```shell
    kubectl apply -f deployments/deployment/nginx-ingress.yaml
    ```

- For NGINX Plus, run:

    ```shell
    kubectl apply -f deployments/deployment/nginx-plus-ingress.yaml
    ```

    Update the `nginx-plus-ingress.yaml` file to include your chosen image from the F5 Container registry or your custom container image.

### Using a DaemonSet

For additional context on managing containers using Kubernetes DaemonSets, refer to the official Kubernetes [DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) documentation.

When you deploy NGINX Ingress Controller as a DaemonSet, Kubernetes creates an Ingress Controller pod on every node in the cluster.

- For NGINX, run:

    ```shell
    kubectl apply -f deployments/daemon-set/nginx-ingress.yaml
    ```

- For NGINX Plus, run:

    ```shell
    kubectl apply -f deployments/daemon-set/nginx-plus-ingress.yaml
    ```

    Update the `nginx-plus-ingress.yaml` file to include your chosen image from the F5 Container registry or your custom container image.

### Using a StatefulSet

For additional context on managing containers using Kubernetes StatefulSets, refer to the official Kubernetes [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) documentation.

When you deploy NGINX Ingress Controller as a StatefulSet, Kubernetes creates pods with stable network identities and persistent storage.

- For NGINX, run:

    ```shell
    kubectl apply -f deployments/stateful-set/nginx-ingress.yaml
    ```

- For NGINX Plus, run:

    ```shell
    kubectl apply -f deployments/stateful-set/nginx-plus-ingress.yaml
    ```

    Update the `nginx-plus-ingress.yaml` file to include your chosen image from the F5 Container registry or your custom container image.

**Note:** 
StatefulSets include persistent volume claims for nginx cache storage via `volumeClaimTemplates`. You may need to configure a StorageClass in your cluster or modify the volumeClaimTemplates section in the manifest to match your storage requirements. Other volumes (like those needed for App Protect modules) are configured in the regular `volumes` section, not in volumeClaimTemplates.

## Confirm NGINX Ingress Controller LTS is running

To confirm the NGINX Ingress Controller pods are operational, run:

```shell
kubectl get pods --namespace=nginx-ingress
```

## How to access NGINX Ingress Controller LTS

### Using a Deployment or StatefulSet

For Deployments and StatefulSets, you have two options for accessing NGINX Ingress Controller LTS pods.

#### Option 1: Create a NodePort service

For more information about the  _NodePort_ service, refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport).

1. To create a service of type *NodePort*, run:

    ```shell
    kubectl create -f deployments/service/nodeport.yaml
    ```

    Kubernetes automatically allocates two ports on every node in the cluster. You can access NGINX Ingress Controller LTS by combining any node's IP address with these ports.

#### Option 2: Create a LoadBalancer service

For more information about the _LoadBalancer_ service, refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/service/#type-loadbalancer).

1. To set up a _LoadBalancer_ service, run one of the following commands based on your cloud provider:

    - GCP or Azure:

        ```shell
        kubectl apply -f deployments/service/loadbalancer.yaml
        ```

    - AWS:

        ```shell
        kubectl apply -f deployments/service/loadbalancer-aws-elb.yaml
        ```

        For more details see service guide [here](https://kubernetes-sigs.github.io/aws-load-balancer-controller/latest/guide/service/annotations/#annotations)

2. AWS users: Follow these additional steps to work with ELB in TCP mode.

     - Add the following keys to the `nginx-config.yaml` ConfigMap file, which you created in the [Create common resources](#create-common-resources) section.

         ```yaml
         proxy-protocol: "True"
         real-ip-header: "proxy_protocol"
         set-real-ip-from: "0.0.0.0/0"
         ```

     - Update the ConfigMap:

         ```shell
         kubectl apply -f deployments/common/nginx-config.yaml
         ```

    **note:** AWS users have more customization options for their load balancers. These include choosing the load balancer type and configuring SSL termination. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/service/#type-loadbalancer) to learn more. 

3. To access NGINX Ingress Controller LTS, get the public IP of your load balancer.

    - For GCP or Azure, run:

        ```shell
        kubectl get svc nginx-ingress --namespace=nginx-ingress
        ```

    - For AWS find the DNS name:

        ```shell
        kubectl describe svc nginx-ingress --namespace=nginx-ingress
        ```

        Resolve the DNS name into an IP address using `nslookup`:

        ```shell
        nslookup <dns-name>
        ```

    You can also find more details about the public IP in the status section of an ingress resource. For more details, refer to the [Reporting Resources Status doc](/nic/lts/configuration/global-configuration/reporting-resources-status.md).

### Using a DaemonSet

Connect to ports 80 and 443 using the IP address of any node in the cluster where NGINX Ingress Controller LTS is running.

## Uninstall NGINX Ingress Controller LTS

**warning:** Proceed with caution when performing these steps, as they will remove NGINX Ingress Controller LTS and all related resources, potentially affecting your running services.

1. **Delete the nginx-ingress namespace**: To remove NGINX Ingress Controller LTS and all auxiliary resources, run:

    ```shell
    kubectl delete namespace nginx-ingress
    ```

1. **Remove the cluster role and cluster role binding**:

    ```shell
    kubectl delete clusterrole nginx-ingress
    kubectl delete clusterrolebinding nginx-ingress
    ```

1. **Delete the Custom Resource Definitions**:

#### Deleting CRDs from single YAML

Delete core custom resource definitions:

```shell
kubectl delete -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v/deploy/crds.yaml
```

#### Deleting CRDs after cloning the repo

Delete core custom resource definitions:

```shell
kubectl delete -f config/crd/bases/crds.yaml
```