github.com/nginxinc/kubernetes-ingress@v1.12.5/docs-web/configuration/ingress-resources/basic-configuration.md (about)

     1  # Basic Configuration
     2  
     3  The example below shows a basic Ingress resource definition. It load balances requests for two services -- coffee and tea -- comprising a hypothetical *cafe* app hosted at `cafe.example.com`:
     4  ```yaml
     5  apiVersion: networking.k8s.io/v1beta1
     6  kind: Ingress
     7  metadata:
     8    name: cafe-ingress
     9  spec:
    10    tls:
    11    - hosts:
    12      - cafe.example.com
    13      secretName: cafe-secret
    14    rules:
    15    - host: cafe.example.com
    16      http:
    17        paths:
    18        - path: /tea
    19          backend:
    20            serviceName: tea-svc
    21            servicePort: 80
    22        - path: /coffee
    23          backend:
    24            serviceName: coffee-svc
    25            servicePort: 80
    26  ```
    27  
    28  Here is a breakdown of what this Ingress resource definition means:
    29  * The `metadata.name` field defines the name of the resource `cafe‑ingress`.
    30  * In the `spec.tls` field we set up SSL/TLS termination:
    31      * In the `secretName`, we reference a secret resource by its name, `cafe‑secret`. The secret must belong to the same namespace as the Ingress, it must be of the type ``kubernetes.io/tls`` and contain keys named ``tls.crt`` and ``tls.key`` that hold the certificate and private key as described [here](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls>). If the secret doesn't exist or is invalid, NGINX will break any attempt to establish a TLS connection to the hosts to which the secret is applied.
    32      * In the `hosts` field, we apply the certificate and key to our `cafe.example.com` host.
    33  * In the `spec.rules` field, we define a host with domain name `cafe.example.com`.
    34  * In the `paths` field, we define two path‑based rules:
    35    * The rule with the path `/tea` instructs NGINX to distribute the requests with the `/tea` URI among the pods of the *tea* service, which is deployed with the name `tea‑svc` in the cluster.
    36    * The rule with the path `/coffee` instructs NGINX to distribute the requests with the `/coffee` URI among the pods of the *coffee* service, which is deployed with the name `coffee‑svc` in the cluster.
    37    * Both rules instruct NGINX to distribute the requests to `port 80` of the corresponding service (the `servicePort` field).
    38  
    39  > For complete instructions on deploying the Ingress and Secret resources in the cluster, see the [complete-example](https://github.com/nginxinc/kubernetes-ingress/tree/v1.12.5/examples/complete-example) in our GitHub repo.
    40  
    41  > To learn more about the Ingress resource, see the [Ingress resource documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/) in the Kubernetes docs.
    42  
    43  ## New Features Available in Kubernetes 1.18 and Above
    44  
    45  Starting from Kubernetes 1.18, you can use the following new features:
    46  
    47  * The host field supports wildcard domain names, such as `*.example.com`.
    48  * The path supports different matching rules with the new field `PathType`, which takes the following values: `Prefix` for prefix-based matching, `Exact` for exact matching and `ImplementationSpecific`, which is the default type and is the same as `Prefix`. For example:
    49    ```yaml
    50      - path: /tea
    51        pathType: Prefix
    52        backend:
    53          serviceName: tea-svc
    54          servicePort: 80
    55      - path: /tea/green
    56        pathType: Exact
    57        backend:
    58          serviceName: tea-svc
    59          servicePort: 80
    60      - path: /coffee
    61        pathType: ImplementationSpecific # default
    62        backend:
    63          serviceName: coffee-svc
    64          servicePort: 80
    65    ```
    66  * The `ingressClassName` field is now supported:
    67    ```yaml
    68      apiVersion: networking.k8s.io/v1beta1
    69      kind: Ingress
    70      metadata:
    71        name: cafe-ingress
    72      spec:
    73        ingressClassName: nginx
    74        tls:
    75        - hosts:
    76          - cafe.example.com
    77          secretName: cafe-secret
    78        rules:
    79        - host: cafe.example.com
    80      . . .
    81    ```
    82    When using this filed you need to create the `IngressClass` resource with the corresponding `name`. See Step 3 *Create an IngressClass resource* of the [Create Common Resources](/nginx-ingress-controller/installation/installation-with-manifests/#create-common-resources) section.
    83  
    84  ## Restrictions
    85  
    86  The NGINX Ingress Controller imposes the following restrictions on Ingress resources:
    87  * When defining an Ingress resource, the `host` field is required.
    88  * The `host` value needs to be unique among all Ingress and VirtualServer resources unless the Ingress resource is a [mergeable minion](/nginx-ingress-controller/configuration/ingress-resources/cross-namespace-configuration/). See also [Handling Host Collisions](/nginx-ingress-controller/configuration/handling-host-collisions).
    89  
    90  ## Advanced Configuration
    91  
    92  The Ingress resource only allows you to use basic NGINX features -- host and path-based routing and TLS termination. Advanced features like rewriting the request URI or inserting additional response headers are available through annotations. See the [Advanced Configuration with Annotations](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations) doc.
    93  
    94  The Ingress Controller generates NGINX configuration by executing a template file that contains configuration options. These options are set via the Ingress resource and the Ingress Controller's ConfigMap. Advanced NGINX users who require more control over the generated NGINX configurations can use snippets to insert raw NGINX config. See [Advanced Configuration with Snippets](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-snippets) for more information. Additionally, it is possible to customize the template. See [Custom Templates](/nginx-ingress-controller/configuration/global-configuration/custom-templates/) for instructions.