Skip to content

cs_annotations.md

Latest commit

 

History

History
1666 lines (1409 loc) · 53.8 KB

cs_annotations.md

File metadata and controls

1666 lines (1409 loc) · 53.8 KB
copyright
years
2014, 2018
lastupdated 2018-01-16

{:new_window: target="_blank"} {:shortdesc: .shortdesc} {:screen: .screen} {:pre: .pre} {:table: .aria-labeledby="caption"} {:codeblock: .codeblock} {:tip: .tip} {:download: .download}

Ingress annotations

{: #ingress_annotation}

To add capabilities to your application load balancer, you can specify annotations as metadata in an Ingress resource. {: shortdesc}

For general information about Ingress services and how to get started using them, see Configuring public access to an app by using Ingress.

General annotations Name Description
External services proxy-external-service Add path definitions to external services, such as a service hosted in {{site.data.keyword.Bluemix_notm}}.
Private application load balancer routing ALB-ID Route incoming requests to your apps with a private application load balancer.
Rewrite paths rewrite-path Route incoming network traffic to a different path that your back-end app listens on.
Session-affinity with cookies sticky-cookie-services Always route incoming network traffic to the same upstream server by using a sticky cookie.
TCP ports tcp-ports Access an app via a non-standard TCP port.
Connection annotations Name Description
Custom connect-timeouts and read-timeouts proxy-connect-timeout Adjust the time that the application load balancer waits to connect to and read from the back-end app before the back-end app is considered unavailable.
Keepalive requests keepalive-requests Configure the maximum number of requests that can be served through one keepalive connection.
Keepalive timeout keepalive-timeout Configure the time that a keepalive connection stays open on the server.
Upstream keepalive upstream-keepalive Configure the maximum number of idle keepalive connections for an upstream server.
Proxy buffer annotations Name Description
Client response data buffering proxy-buffering Disable the buffering of a client response on the application load balancer while sending the response to the client.
Proxy buffers proxy-buffers Set the number and size of the buffers that read a response for a single connection from the proxied server.
Proxy buffer size proxy-buffer-size Set the size of the buffer that reads the first part of the response that is received from the proxied server.
Proxy busy buffers size proxy-busy-buffers-size Set the size of proxy buffers that can be busy.
Request and response annotations Name Description
Additional client request or response header proxy-add-headers Add header information to a client request before forwarding the request to your back-end app or to a client response before sending the response to the client.
Client response header removal response-remove-headers Remove header information from a client response before forwarding the response to the client.
Custom maximum client request body size client-max-body-size Adjust the size of the client request body that is allowed to be sent to the application load balancer.
Service limit annotations Name Description
Global rate limits global-rate-limit Limit the request processing rate and number of connections per a defined key for all services.
Service rate limits service-rate-limit Limit the request processing rate and the number of connections per a defined key for specific services.
HTTPS and TLS/SSL authentication annotations Name Description
Custom HTTP and HTTPS ports custom-port Change the default ports for HTTP (port 80) and HTTPS (port 443) network traffic.
HTTP redirects to HTTPS redirect-to-https Redirect insecure HTTP requests on your domain to HTTPS.
Mutual authentication mutual-auth Configure mutual authentication for the application load balancer.
SSL services support ssl-services Allow SSL services support for load balancing.

General annotations

{: #general}

External services (proxy-external-service)

{: #proxy-external-service}

Add path definitions to external services, such as services hosted in {{site.data.keyword.Bluemix_notm}}. {:shortdesc}

Description
Add path definitions to external services. Use this annotation only when your app operates on an external service instead of a backend service. When you use this annotation to create an external service route, only `client-max-body-size`, `proxy-read-timeout`, `proxy-connect-timeout`, and `proxy-buffering` annotations are supported in conjunction. Any other annotations are not supported in conjunction with `proxy-external-service`.
Sample Ingress resource YAML

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: cafe-ingress
  annotations:
    ingress.bluemix.net/proxy-external-service: "path=<mypath> external-svc=https:<external_service> host=<mydomain>"
spec:
  tls:
  - hosts:
    - mydomain
    secretName: mysecret
  rules:
  - host: mydomain
    http:
      paths:
      - path: /
        backend:
          serviceName: myservice
          servicePort: 80
Idea icon Understanding the YAML file components
path Replace <mypath> with the path that the external service listens on.
external-svc Replace <external_service> with the external service to be called. For example, https://<myservice>.<region>.mybluemix.net.
host Replace <mydomain> with the host domain for the external service.

Private application load balancer routing (ALB-ID)

{: #alb-id}

Route incoming requests to your apps with a private application load balancer. {:shortdesc}

Description
Choose a private application load balancer to route incoming requests with instead of the public application load balancer.
Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: myingress
annotations:
  ingress.bluemix.net/ALB-ID: "<private_ALB_ID>"
spec:
tls:
- hosts:
  - mydomain
  secretName: mytlssecret
rules:
- host: mydomain
  http:
    paths:
    - path: /
      backend:
        serviceName: myservice
        servicePort: 8080
Idea icon Understanding the YAML file components
<private_ALB_ID> The ID for your private application load balancer. Run bx cs albs --cluster to find the private application load balancer ID.

Rewrite paths (rewrite-path)

{: #rewrite-path}

Route incoming network traffic on an application load balancer domain path to a different path that your back-end application listens on. {:shortdesc}

Description
Your Ingress application load balancer domain routes incoming network traffic on mykubecluster.us-south.containers.mybluemix.net/beans to your app. Your app listens on /coffee, instead of /beans. To forward incoming network traffic to your app, add the rewrite annotation to your Ingress resource configuration file. The rewrite annotation ensures that incoming network traffic on /beans is forwarded to your app by using the /coffee path. When including multiple services, use only a semi-colon (;) to separate them.
Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: myingress
  annotations:
    ingress.bluemix.net/rewrite-path: "serviceName=<myservice1> rewrite=<target_path1>;serviceName=<myservice2> rewrite=<target_path2>"
spec:
  tls:
  - hosts:
    - mydomain
    secretName: mysecret
  rules:
  - host: mydomain
    http:
      paths:
      - path: /beans
        backend:
          serviceName: myservice1
          servicePort: 80
Idea icon Understanding the YAML file components
serviceName Replace <myservice> with the name of the Kubernetes service that you created for your app.
rewrite Replace <target_path> with the path that your app listens on. Incoming network traffic on the application load balancer domain is forwarded to the Kubernetes service by using this path. Most apps do not listen on a specific path, but use the root path and a specific port. In the example above, the rewrite path was defined as /coffee.

Session-affinity with cookies (sticky-cookie-services)

{: #sticky-cookie-services}

Use the sticky cookie annotation to add session affinity to your application load balancer and always route incoming network traffic to the same upstream server. {:shortdesc}

Description
For high availability, some app setups require you to deploy multiple upstream servers that handle incoming client requests. When a client connects to you back-end app, you can use session-affinity so that a client is served by the same upstream server for the duration of a session or for the time it takes to complete a task. You can configure your application load balancer to ensure session-affinity by always routing incoming network traffic to the same upstream server.



Every client that connects to your back-end app is assigned to one of the available upstream servers by the application load balancer. The application load balancer creates a session cookie that is stored in the client's app, which is included in the header information of every request between the application load balancer and the client. The information in the cookie ensures that all requests are handled by the same upstream server throughout the session.



When you include multiple services, use a semi-colon (;) to separate them.

Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: myingress
  annotations:
    ingress.bluemix.net/sticky-cookie-services: "serviceName=<myservice1> name=<cookie_name1> expires=<expiration_time1> path=<cookie_path1> hash=<hash_algorithm1>;serviceName=<myservice2> name=<cookie_name2> expires=<expiration_time2> path=<cookie_path2> hash=<hash_algorithm2>"
spec:
  tls:
  - hosts:
    - mydomain
    secretName: mytlssecret
  rules:
  - host: mydomain
    http:
      paths:
      - path: /
        backend:
          serviceName: <myservice1>
          servicePort: 8080
      - path: /myapp
        backend:
          serviceName: <myservice2>
          servicePort: 80
Understanding the YAML file components
Idea icon Understanding the YAML file components
serviceName Replace <myservice> with the name of the Kubernetes service that you created for your app.
name Replace <cookie_name> with the name of a sticky cookie that is created during a session.
expires Replace <expiration_time> with the time in seconds (s), minutes (m), or hours (h) before the sticky cookie expires. This time is independent of the user activity. After the cookie is expired, the cookie is deleted by the client web browser and no longer sent to the application load balancer. For example, to set an expiration time of 1 second, 1 minute, or 1 hour, enter 1s, 1m, or 1h.
path Replace <cookie_path> with the path that is appended to the Ingress subdomain and that indicates for which domains and subdomains the cookie is sent to the application load balancer. For example, if your Ingress domain is www.myingress.com and you want to send the cookie in every client request, you must set path=/. If you want to send the cookie only for www.myingress.com/myapp and all its subdomains, then you must set path=/myapp.
hash Replace <hash_algorithm> with the hash algorithm that protects the information in the cookie. Only sha1 is supported. SHA1 creates a hash sum based on the information in the cookie and appends this hash sum to the cookie. The server can decrypt the information in the cookie and verify data integrity.

TCP ports for application load balancers (tcp-ports)

{: #tcp-ports}

Access an app via a non-standard TCP port. {:shortdesc}

Description
Use this annotation for an app that is running a TCP streams workload.

**Note**: The application load balancer operates in pass-through mode and forwards traffic to backend apps. SSL termination is not supported in this case.

Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: myingress
annotations:
  ingress.bluemix.net/tcp-ports: "serviceName=<myservice> ingressPort=<ingress_port> [servicePort=<service_port>]"
spec:
  tls:
  - hosts:
    - mydomain
    secretName: mysecret
  rules:
  - host: mydomain
    http:
      paths:
      - path: /
        backend:
          serviceName: <myservice>
          servicePort: 80
Idea icon Understanding the YAML file components
serviceName Replace <myservice> with the name of the Kubernetes service to access over non-standard TCP port.
ingressPort Replace <ingress_port> with the TCP port on which you want to access your app.
servicePort This parameter is optional. When provided, the port is substituted to this value before traffic is sent to the backend app. Otherwise, the port remains same as the Ingress port.

Connection annotations

{: #connection}

Custom connect-timeouts and read-timeouts (proxy-connect-timeout, proxy-read-timeout)

{: #proxy-connect-timeout}

Set a custom connect-timeout and read-timeout for the application load balancer. Adjust the time that the application load balancer waits to connect to and read from the back-end app before the back-end app is considered unavailable. {:shortdesc}

Description
When a client request is sent to the Ingress application load balancer, a connection to the back-end app is opened by the application load balancer. By default, the application load balancer waits 60 seconds to receive a reply from the back-end app. If the back-end app does not reply within 60 seconds, then the connection request is aborted and the back-end app is considered to be unavailable.



After the application load balancer is connected to the back-end app, response data is read from the back-end app by the application load balancer. During this read operation, the application load balancer waits a maximum of 60 seconds between two read operations to receive data from the back-end app. If the back-end app does not send data within 60 seconds, the connection to the back-end app is closed and the app is considered to be not available.

A 60 second connect-timeout and read-timeout is the default timeout on a proxy and usually should not be changed.

If the availability of your app is not steady or your app is slow to respond because of high workloads, you might want to increase the connect-timeout or read-timeout. Keep in mind that increasing the timeout impacts the performance of the application load balancer as the connection to the back-end app must stay open until the timeout is reached.

On the other hand, you can decrease the timeout to gain performance on the application load balancer. Ensure that your back-end app is able to handle requests within the specified timeout, even during higher workloads.

Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
 name: myingress
 annotations:
   ingress.bluemix.net/proxy-connect-timeout: "<connect_timeout>s"
   ingress.bluemix.net/proxy-read-timeout: "<read_timeout>s"
spec:
 tls:
 - hosts:
   - mydomain
   secretName: mytlssecret
 rules:
 - host: mydomain
   http:
     paths:
     - path: /
       backend:
         serviceName: myservice
         servicePort: 8080
Idea icon Understanding the YAML file components
<connect_timeout> The number of seconds to wait to connect to the back-end app, for example 65s. Note: A connect-timeout cannot exceed 75 seconds.
<read_timeout> The number of seconds to wait before the back-end app is read, for example 65s. Note: A read-timeout cannot exceed 120 seconds.

Keepalive requests (keepalive-requests)

{: #keepalive-requests}

Configure the maximum number of requests that can be served through one keepalive connection. {:shortdesc}

Description
Sets the maximum number of requests that can be served through one keepalive connection.
Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: myingress
annotations:
  ingress.bluemix.net/keepalive-requests: "serviceName=<myservice> requests=<max_requests>"
spec:
tls:
- hosts:
  - mydomain
  secretName: mytlssecret
rules:
- host: mydomain
  http:
    paths:
    - path: /
      backend:
        serviceName: <myservice>
        servicePort: 8080
Idea icon Understanding the YAML file components
serviceName Replace <myservice> with the name of the Kubernetes service that you created for your app. This parameter is optional. The configuration is applied to all of the services in the Ingress host unless a service is specified. If the parameter is provided, the keepalive requests are set for the given service. If the parameter is not provided, the keepalive requests are set at the server level of the nginx.conf for all the services that do not have the keepalive requests configured.
requests Replace <max_requests> with the maximum number of requests that can be served through one keepalive connection.

Keepalive timeout (keepalive-timeout)

{: #keepalive-timeout}

Configure the time that a keepalive connection stays open on the server side. {:shortdesc}

Description
Sets the time that a keepalive connection stays open on the server.
Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
 name: myingress
 annotations:
   ingress.bluemix.net/keepalive-timeout: "serviceName=<myservice> timeout=<time>s"
spec:
 tls:
 - hosts:
   - mydomain
   secretName: mytlssecret
 rules:
 - host: mydomain
   http:
     paths:
     - path: /
       backend:
         serviceName: myservice
         servicePort: 8080
Idea icon Understanding the YAML file components
serviceName Replace <myservice> with the name of the Kubernetes service that you created for your app. This parameter is optional. If the parameter is provided, the keepalive timeout is set for the given service. If the parameter is not provided, the keepalive timeout is set at the server level of the nginx.conf for all the services that do not have the keepalive timeout configured.
timeout Replace <time> with an amount of time in seconds. Example: timeout=20s. A zero value disables the keepalive client connections.

Upstream keepalive (upstream-keepalive)

{: #upstream-keepalive}

Configure the maximum number of idle keepalive connections for an upstream server. {:shortdesc}

Description
Change the maximum number of idle keepalive connections to the upstream server of a given service. The upstream server has 64 idle keepalive connections by default.
Sample Ingress resource YAML
 apiVersion: extensions/v1beta1
 kind: Ingress
 metadata:
  name: myingress
  annotations:
    ingress.bluemix.net/upstream-keepalive: "serviceName=<myservice> keepalive=<max_connections>"
 spec:
  tls:
  - hosts:
    - mydomain
    secretName: mytlssecret
  rules:
  - host: mydomain
    http:
      paths:
      - path: /
        backend:
          serviceName: myservice
          servicePort: 8080
Idea icon Understanding the YAML file components
serviceName Replace <myservice> with the name of the Kubernetes service that you created for your app.
keepalive Replace <max_connections> with the maximum number of idle keepalive connections to the upstream server. The default is 64. A 0 value disables upstream keepalive connections for the given service.

Proxy buffer annotations

{: #proxy-buffer}

Client response data buffering (proxy-buffering)

{: #proxy-buffering}

Use the buffer annotation to disable the storage of response data on the application load balancer while the data is sent to the client. {:shortdesc}

Description
The Ingress application load balancer acts as a proxy between your back-end app and the client web browser. When a response is sent from the back-end app to the client, the response data is buffered on the application load balancer by default. The application load balancer proxies the client response and starts sending the response to the client at the client's pace. After all data from the back-end app is received by the application load balancer, the connection to the back-end app is closed. The connection from the application load balancer to the client remains open until the client receives all data.



If buffering of response data on the application load balancer is disabled, data is immediately sent from the application load balancer to the client. The client must be able to handle incoming data at the pace of the application load balancer. If the client is too slow, data might get lost.

Response data buffering on the application load balancer is enabled by default.

Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
 name: myingress
 annotations:
   ingress.bluemix.net/proxy-buffering: "False"
spec:
 tls:
 - hosts:
   - mydomain
   secretName: mytlssecret
 rules:
 - host: mydomain
   http:
     paths:
     - path: /
       backend:
         serviceName: myservice
         servicePort: 8080

Proxy buffers (proxy-buffers)

{: #proxy-buffers}

Configure the number and size of proxy buffers for the application load balancer. {:shortdesc}

Description
Set the number and size of the buffers that read a response for a single connection from the proxied server. The configuration is applied to all of the services in the Ingress host unless a service is specified. For example, if a configuration such as serviceName=SERVICE number=2 size=1k is specified, 1k is applied to the service. If a configuration such as number=2 size=1k is specified, 1k is applied to all of the services in the Ingress host.
Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
 name: proxy-ingress
 annotations:
   ingress.bluemix.net/proxy-buffers: "serviceName=<myservice> number=<number_of_buffers> size=<size>"
spec:
 tls:
 - hosts:
   - mydomain
   secretName: mytlssecret
 rules:
 - host: mydomain
   http:
     paths:
     - path: /
       backend:
         serviceName: myservice
         servicePort: 8080
Idea icon Understanding the YAML file components
serviceName Replace <myservice> with the name for a service to apply proxy-buffers.
number_of_buffers Replace <number_of_buffers> with a number, such as 2.
size Replace <size> with the size of each buffer in kilobytes (k or K), such as 1K.

Proxy buffer size (proxy-buffer-size)

{: #proxy-buffer-size}

Configure the size of the proxy buffer that reads the first part of the response. {:shortdesc}

Description
Set the size of the buffer that reads the first part of the response that is received from the proxied server. This part of the response usually contains a small response header. The configuration is applied to all of the services in the Ingress host unless a service is specified. For example, if a configuration such as serviceName=SERVICE size=1k is specified, 1k is applied to the service. If a configuration such as size=1k is specified, 1k is applied to all of the services in the Ingress host.
Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
 name: proxy-ingress
 annotations:
   ingress.bluemix.net/proxy-buffer-size: "serviceName=<myservice> size=<size>"
spec:
 tls:
 - hosts:
   - mydomain
   secretName: mytlssecret
 rules:
 - host: mydomain
   http:
     paths:
     - path: /
       backend:
         serviceName: myservice
         servicePort: 8080
Idea icon Understanding the YAML file components
serviceName Replace <myservice> with the name of a service to apply proxy-buffers-size.
size Replace <size> with the size of each buffer in kilobytes (k or K), such as 1K.

Proxy busy buffers size (proxy-busy-buffers-size)

{: #proxy-busy-buffers-size}

Configure the size of proxy buffers that can be busy. {:shortdesc}

Description
Limit the size of any buffers that are sending a response to the client while the response is not yet fully read. In the meantime, the rest of the buffers can read the response and, if needed, buffer part of the response to a temporary file. The configuration is applied to all of the services in the Ingress host unless a service is specified. For example, if a configuration such as serviceName=SERVICE size=1k is specified, 1k is applied to the service. If a configuration such as size=1k is specified, 1k is applied to all of the services in the Ingress host.
Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
 name: proxy-ingress
 annotations:
   ingress.bluemix.net/proxy-busy-buffers-size: "serviceName=<serviceName> size=<size>"
spec:
 tls:
 - hosts:
   - mydomain
   secretName: mytlssecret
 rules:
 - host: mydomain
   http:
     paths:
     - path: /
       backend:
         serviceName: myservice
         servicePort: 8080
Idea icon Understanding the YAML file components
serviceName Replace <myservice> with the name of a service to apply proxy-busy-buffers-size.
size Replace <size> with the size of each buffer in kilobytes (k or K), such as 1K.

Request and response annotations

{: #request-response}

Additional client request or response header (proxy-add-headers)

{: #proxy-add-headers}

Add extra header information to a client request before sending the request to the back-end app or to a client response before sending the response to the client. {:shortdesc}

Description
The Ingress application load balancer acts as a proxy between the client app and your back-end app. Client requests that are sent to the application load balancer are processed (proxied) and put into a new request that is then sent from the application load balancer to your back-end app. Proxying a request removes http header information, such as the user name, that was initially sent from the client. If your back-end app requires this information, you can use the ingress.bluemix.net/proxy-add-headers annotation to add header information to the client request before the request is forwarded from the application load balancer to your back-end app.



When a back-end app sends a response to the client, the response is proxied by the application load balancer and http headers are removed from the response. The client web app might require this header information to successfully process the response. You can use the ingress.bluemix.net/response-add-headers annotation to add header information to the client response before the response is forwarded from the application load balancer to client web app.

Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: myingress
  annotations:
    ingress.bluemix.net/proxy-add-headers: |
      serviceName=<myservice1> {
      <header1> <value1>;
      <header2> <value2>;
      }
      serviceName=<myservice2> {
      <header3> <value3>;
      }
    ingress.bluemix.net/response-add-headers: |
      serviceName=<myservice1> {
      "<header1>: <value1>";
      "<header2>: <value2>";
      }
      serviceName=<myservice2> {
      "<header3>: <value3>";
      }
spec:
  tls:
  - hosts:
    - mydomain
    secretName: mytlssecret
  rules:
  - host: mydomain
    http:
      paths:
      - path: /
        backend:
          serviceName: <myservice1>
          servicePort: 8080
      - path: /myapp
        backend:
          serviceName: <myservice2>
          servicePort: 80
Idea icon Understanding the YAML file components
service_name Replace <myservice> with the name of the Kubernetes service that you created for your app.
<header> The key of the header information to add to the client request or client response.
<value> The value of the header information to add to the client request or client response.

Client response header removal (response-remove-headers)

{: #response-remove-headers}

Remove header information that is included in the client response from the back-end end app before the response is sent to the client. {:shortdesc}

Description
The Ingress application load balancer acts as a proxy between your back-end app and the client web browser. Client responses from the back-end app that are sent to the application load balancer are processed (proxied), and put into a new response that is then sent from the application load balancer to the client web browser. Although proxying a response removes http header information that was initially sent from the back-end app, this process might not remove all back-end app specific headers. Remove header information from a client reponse before the response is forwarded from the application load balancer to the client web browser.
Sample Infress resource YAML
 apiVersion: extensions/v1beta1
 kind: Ingress
 metadata:
   name: myingress
   annotations:
     ingress.bluemix.net/response-remove-headers: |
       serviceName=<myservice1> {
       "<header1>";
       "<header2>";
       }
       serviceName=<myservice2> {
       "<header3>";
       }
 spec:
   tls:
   - hosts:
     - mydomain
     secretName: mytlssecret
   rules:
   - host: mydomain
     http:
       paths:
       - path: /
         backend:
           serviceName: <myservice1>
           servicePort: 8080
       - path: /myapp
         backend:
           serviceName: <myservice2>
           servicePort: 80
Idea icon Understanding the YAML file components
service_name Replace <myservice> with the name of the Kubernetes service that you created for your app.
<header> The key of the header to remove from the client response.

Custom maximum client request body size (client-max-body-size)

{: #client-max-body-size}

Adjust the maximum size of the body that the client can send as part of a request. {:shortdesc}

Description
To maintain the expected performance, the maximum client request body size is set to 1 megabyte. When a client request with a body size over the limit is sent to the Ingress application load balancer, and the client does not allow data to be divided, the application load balancer returns a 413 (Request Entity Too Large) HTTP response to the client. A connection between the client and the application load balancer is not possible until the size of the request body is reduced. When the client allows data to be split up into multiple chunks, data is divided into packages of 1 megabyte and sent to the application load balancer.



You might want to increase the maximum body size because you expect client requests with a body size that is greater than 1 megabyte. For example, you want your client to be able to upload large files. Increasing the maximum request body size might impact the performance of your application load balancer because the connection to the client must stay open until the request is received.

Note: Some client web browsers cannot display the 413 HTTP response message properly.

Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
 name: myingress
 annotations:
   ingress.bluemix.net/client-max-body-size: "size=<size>"
spec:
 tls:
 - hosts:
   - mydomain
   secretName: mytlssecret
 rules:
 - host: mydomain
   http:
     paths:
     - path: /
       backend:
         serviceName: myservice
         servicePort: 8080
Idea icon Understanding the YAML file components
<size> The maximum size of the client response body. For example, to set it to 200 megabyte, define 200m. Note: You can set the size to 0 to disable the check of the client request body size.

Service limit annotations

{: #service-limit}

Global rate limits (global-rate-limit)

{: #global-rate-limit}

Limit the request processing rate and number of connections per a defined key for all services. {:shortdesc}

Description
For all services, limit the request processing rate and the number of connections per a defined key that are coming from a single IP address for all paths of the selected backends.
Sample Ingress resource YAML
 apiVersion: extensions/v1beta1
 kind: Ingress
 metadata:
  name: myingress
  annotations:
    ingress.bluemix.net/global-rate-limit: "key=<key> rate=<rate> conn=<number_of_connections>"
 spec:
  tls:
  - hosts:
    - mydomain
    secretName: mytlssecret
  rules:
  - host: mydomain
    http:
      paths:
      - path: /
        backend:
          serviceName: myservice
          servicePort: 8080
Idea icon Understanding the YAML file components
key To set a global limit for incoming requests based on the location or service, use `key=location`. To set a global limit for incoming requests based on the header, use `X-USER-ID key==$http_x_user_id`.
rate Replace <rate> with the processing rate. Enter a value as a rate per second (r/s) or rate per minute (r/m). Example: 50r/m.
number-of_connections Replace <conn> with the number of connections.

Service rate limits (service-rate-limit)

{: #service-rate-limit}

Limit the request processing rate and the number of connections for specific services. {:shortdesc}

Description
For specific services, limit the request processing rate and the number of connections per a defined key that are coming from a single IP address for all paths of the selected backends.
Sample Ingress resource YAML
 apiVersion: extensions/v1beta1
 kind: Ingress
 metadata:
  name: myingress
  annotations:
    ingress.bluemix.net/service-rate-limit: "serviceName=<myservice> key=<key> rate=<rate> conn=<number_of_connections>"
 spec:
  tls:
  - hosts:
    - mydomain
    secretName: mytlssecret
  rules:
  - host: mydomain
    http:
      paths:
      - path: /
        backend:
          serviceName: myservice
          servicePort: 8080
Idea icon Understanding the YAML file components
serviceName Replace <myservice> with the name of the service for which you want to limit the processing rate.
key To set a global limit for incoming requests based on the location or service, use `key=location`. To set a global limit for incoming requests based on the header, use `X-USER-ID key==$http_x_user_id`.
rate Replace <rate> with the processing rate. To define a rate per second, use r/s: 10r/s. To define a rate per minute, use r/m: 50r/m.
number-of_connections Replace <conn> with the number of connections.

HTTPS and TLS/SSL authentication annotations

{: #https-auth}

Custom HTTP and HTTPS ports (custom-port)

{: #custom-port}

Change the default ports for HTTP (port 80) and HTTPS (port 443) network traffic. {:shortdesc}

Description
By default, the Ingress application load balancer is configured to listen for incoming HTTP network traffic on port 80 and for incoming HTTPS network traffic on port 443. You can change the default ports to add security to your application load balancer domain, or to enable only an HTTPS port.
Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
 name: myingress
 annotations:
   ingress.bluemix.net/custom-port: "protocol=<protocol1> port=<port1>;protocol=<protocol2> port=<port2>"
spec:
 tls:
 - hosts:
   - mydomain
   secretName: mytlssecret
 rules:
 - host: mydomain
   http:
     paths:
     - path: /
       backend:
         serviceName: myservice
         servicePort: 8080
Idea icon Understanding the YAML file components
<protocol> Enter http or https to change the default port for incoming HTTP or HTTPS network traffic.
<port> Enter the port number that you want to use for incoming HTTP or HTTPS network traffic.

Note: When a custom port is specified for either HTTP or HTTPS, the default ports are no longer valid for both HTTP and HTTPS. For example, to change the default port for HTTPS to 8443, but use the default port for HTTP, you must set custom ports for both: custom-port: "protocol=http port=80; protocol=https port=8443".
Usage
  1. Review open ports for your application load balancer. 
    kubectl get service -n kube-system
    Your CLI output looks similar to the following: 
    NAME                     CLUSTER-IP     EXTERNAL-IP     PORT(S)                      AGE
public-ingress-ctl-svc   10.10.10.149   169.60.16.246   80:30776/TCP,443:30412/TCP   8d
  2. Open the Ingress controller config map. 
    kubectl edit configmap ibm-cloud-provider-ingress-cm -n kube-system
  3. Add the non-default HTTP and HTTPS ports to the config map. Replace <port> with the HTTP or HTTPS port that you want to open. 
    apiVersion: v1
kind: ConfigMap
data:
 public-ports: <port1>;<port2>
metadata:
 creationTimestamp: 2017-08-22T19:06:51Z
 name: ibm-cloud-provider-ingress-cm
 namespace: kube-system
 resourceVersion: "1320"
 selfLink: /api/v1/namespaces/kube-system/configmaps/ibm-cloud-provider-ingress-cm
 uid: <uid>
  4. Verify that your Ingress controller is re-configured with the non-default ports. 
    kubectl get service -n kube-system
    Your CLI output looks similar to the following: 
    NAME                     CLUSTER-IP     EXTERNAL-IP     PORT(S)                      AGE
public-ingress-ctl-svc   10.10.10.149   169.60.16.246   <port1>:30776/TCP,<port2>:30412/TCP   8d
  5. Configure your Ingress to use the non-default ports when routing incoming network traffic to your services. Use the sample YAML file in this reference.
  6. Update your Ingress controller configuration. 
    kubectl apply -f <yaml_file>
  7. Open your preferred web browser to access your app. Example: https://<ibmdomain>:<port>/<service_path>/

HTTP redirects to HTTPS (redirect-to-https)

{: #redirect-to-https}

Convert insecure HTTP client requests to HTTPS. {:shortdesc}

Description
You set up your Ingress application load balancer to secure your domain with the IBM-provided TLS certificate or your custom TLS certificate. Some users might try to access your apps by using an insecure http request to your application load balancer domain, for example http://www.myingress.com, instead of using https. You can use the redirect annotation to always convert insecure HTTP requests to HTTPS. If you do not use this annotation, insecure HTTP requests are not converted into HTTPS requests by default and might expose unencrypted confidential information to the public.



Redirecting HTTP requests to HTTPS is disabled by default.

Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
 name: myingress
 annotations:
   ingress.bluemix.net/redirect-to-https: "True"
spec:
 tls:
 - hosts:
   - mydomain
   secretName: mytlssecret
 rules:
 - host: mydomain
   http:
     paths:
     - path: /
       backend:
         serviceName: myservice
         servicePort: 8080

Mutual authentication (mutual-auth)

{: #mutual-auth}

Configure mutual authentication for the application load balancer. {:shortdesc}

Description
Configure mutual authentication for the Ingress application load balancer. The client authenticates the server and the server also authenticates the client by using certificates. Mutual authentication is also known as certificate-based authentication or two-way authentication.
Pre-requisites
  • [You must have a valid secret that contains the required certificate authority (CA)](cs_app.html#secrets). The client.key and client.crt are also needed to authenticate with mutual authentication.
  • To enable mutual authentication on a port other than 443, [configure the load balancer to open the valid port](cs_ingress.html#opening_ingress_ports).
Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: myingress
annotations:
  ingress.bluemix.net/mutual-auth: "secretName=<mysecret> port=<port> serviceName=<servicename1>,<servicename2>"
spec:
  tls:
  - hosts:
    - mydomain
    secretName: mytlssecret
  rules:
  - host: mydomain
    http:
      paths:
      - path: /
        backend:
          serviceName: myservice
          servicePort: 8080
Idea icon Understanding the YAML file components
secretName Replace <mysecret> with a name for the secret resource.
<port> The application load balancer port number.
<serviceName> The name of one or more Ingress resources. This parameter is optional.

SSL services support (ssl-services)

{: #ssl-services}

Allow HTTPS requests and encrypt traffic to your upstream apps. {:shortdesc}

Description
Encrypt traffic to your upstream apps that require HTTPS with the application load balancers.

Optional: You can add one-way authentication or mutual authentication to this annotation.

Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: <myingressname>
  annotations:
    ingress.bluemix.net/ssl-services: "ssl-service=<myservice1> [ssl-secret=<service1-ssl-secret>];ssl-service=<myservice2> [ssl-secret=<service2-ssl-secret>]
spec:
  rules:
  - host: mydomain
    http:
      paths:
      - path: /
        backend:
          serviceName: myservice1
          servicePort: 8443
      - path: /
        backend:
          serviceName: myservice2
          servicePort: 8444
Idea icon Understanding the YAML file components
ssl-service Replace <myservice> with the name of the service that represents your app. Traffic is encrypted from application load balancer to this app.
ssl-secret Replace <service-ssl-secret> with the secret for the service. This parameter is optional. If the parameter is provided, the value must contain the key and the certificate that your app is expecting from the client.

SSL Services support with authentication

{: #ssl-services-auth}

Allow HTTPS requests and encrypt traffic to your upstream apps with one-way or mutual authentication for additional security. {:shortdesc}

Description
Configure mutual authentication for load balancing apps that require HTTPS with the Ingress controllers.

Note: Before you begin, convert the cert and key into base-64 External link icon.

Sample Ingress resource YAML
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: <myingressname>
  annotations:
    ingress.bluemix.net/ssl-services: |
      ssl-service=<myservice1> ssl-secret=<service1-ssl-secret>;
      ssl-service=<myservice2> ssl-secret=<service2-ssl-secret>
spec:
  tls:
  - hosts:
    - mydomain
    secretName: mysecret
  rules:
  - host: mydomain
    http:
      paths:
      - path: /
        backend:
          serviceName: myservice1
          servicePort: 8443
      - path: /
        backend:
          serviceName: myservice2
          servicePort: 8444
Idea icon Understanding the YAML file components
ssl-service Replace <myservice> with the name of the service that represents your app. Traffic is encrypted from application load balancer to this app.
ssl-secret Replace <service-ssl-secret> with the secret for the service. This parameter is optional. If the parameter is provided, the value must contain the key and the certificate that your app is expecting from the client.