Accessing Akamas

To interact with your Akamas instance, you need the UI and API Gateway to be accessible from outside the cluster.

Kubernetes offers different options to expose a service outside of the cluster. The following is a list of the supported ones, with examples of how to configure them to work in your chart release:

• Port Forwarding

• Ingress

While changing the access mode of your Akamas installation, you must also update the value of the akamasBaseUrl option of the Helm Values file to match the new endpoint used.

Port Forwarding

By default, Akams uses Cluster IPs for its services, allowing communication only inside the cluster. Still, you can leverage Kubectl's port-forward to create a private connection and expose any internal service on your local machine.

This solution is suggested to perform quick tests without exposing the application or in scenarios where cluster access to the public is not allowed.

Set akamasBaseUrl to http://localhost:9000 in your Helm Values file, and install or update your Akamas deployment using the Helm command. Once the rollout is complete, open a tunnel to the UI with the following command:

kubectl port-forward service/ui 9000:http

As long as the port-forwarding is running, you will be able to interact with the UI through the tunnel; you can also interact through the Akamas CLI by configuring the URL http://localhost:9000/akapi.

Refer to the official kubernetes documentation for more details about port-forwarding.

Ingress

An Ingress is a Kubernetes object that provides service access, load balancing, and SSL termination to Kubernetes services.

To expose the Akamas UI through an Ingress, configure the Helm Values file by configuring akamasBaseUrl with the host of the Ingress (e.g.: https://akamas.kube.example.com), and by adding the snippet below:

ingress:
  enabled: true
  tls:
    - secretName: "<SECRET_NAME>"  # Secret containing the certificate and key data
  annotations: {}  # Optional

Here is a description of the fields:

• enabled: set to true to enable the Ingress

• tls: configure secretName with the name of the Secret containing the TLS certificate for the hostname configured in akamasBaseUrl. This secret must be created manually before applying the configuration (see TLS Secrets on the Kubernetes documentation) or managed by a certificate issuer configured in the namespace.

• annotations: optional, provide any additional annotation required in your deployment. If your cluster leverages any certificate issuer (such as cert-manager), you can add here the annotations required to interact with the issuer. Additionally, for a detailed explanation of common NGINX-specific annotations that can be configured to optimize the behavior of the Ingress, refer to the section below.

Re-run the install command to update the configuration. Once the rollout is complete, you will be able to access the UI using the URL specified in akamasBaseUrl and interact with the CLI using ${akamasBaseUrl}/api.

Refer to the official kubernetes documentation for more details on Ingresses.

Configuring NGINX Ingress Annotations

When exposing the Akamas UI through an Ingress, additional configuration may be necessary to ensure optimal performance and compatibility, especially when dealing with larger request bodies or specific network behaviors. Below are recommended annotations for the NGINX Ingress Controller that can be added to your Helm Values file:

ingress:
  enabled: true
  tls:
    - secretName: "<SECRET_NAME>"
  annotations:
    nginx.org/proxy-buffering: "true"
    nginx.org/proxy-buffer-size: "16k"
    nginx.org/proxy-buffers: "8 16k"
    nginx.org/server-tokens: "false"
    nginx.org/proxy-read-timeout: "10m"
    nginx.org/client-max-body-size: "50m"

Annotation Descriptions:

• nginx.org/proxy-buffering

  Enables or disables proxy buffering. Enabling proxy buffering can improve performance by reducing disk I/O operations when handling responses from the proxied server.

• nginx.org/proxy-buffer-size

  Sets the size of the buffer used for reading the first part of the response from the proxied server, which includes the response headers. Adjusting this value can help when dealing with large headers.

• nginx.org/proxy-buffers

  Defines the number and size of buffers used for reading a response from the proxied server. This setting can enhance performance when processing large responses.

• nginx.org/server-tokens

  Controls whether NGINX displays its version information on error pages and in the "Server" HTTP response header field. Disabling this can enhance security by not exposing server details.

• nginx.org/proxy-read-timeout

  Sets the timeout duration for reading a response from the proxied server. Adjusting this is useful for long-running requests to prevent timeouts.

• nginx.org/client-max-body-size

  Specifies the maximum allowed size of the client request body. Increasing this limit is necessary when clients need to send larger payloads, such as file uploads or extensive data submissions.

Important Notes:

• Compatibility: These annotations are specific to the NGINX Ingress Controller. If you are using a different Ingress Controller (e.g., Traefik, HAProxy), you will need to consult the respective documentation for equivalent settings.

• Customization: Depending on your environment and requirements, you may need to adjust the values of these annotations. Ensure that any changes are tested in a development or staging environment before applying to production.

• Additional Annotations: Additional configurations may be necessary, according to your specific use case. The NGINX Ingress Controller supports a wide range of annotations for advanced customization.

For more detailed information and additional configuration options, please refer to the official NGINX Ingress Controller documentation: Advanced Configuration with Annotations.