Use the NGINX Service Mesh API

Instructions for using the NGINX Service Mesh API.

Warning:
The NGINX Service Mesh API is in beta release status and is not recommended for use in client-side automation. The objects described here are subject to change as the API evolves. No guarantee of backwards compatibility is made.

Overview

The Service Mesh API is a REST API that offers a way to view and manage resources within the mesh. It can be accessed through REST requests or via the command line tool.

Note:
Refer to the API documentation for endpoint descriptions, request payloads, and response bodies.

Use the REST API

The API server allows for direct REST calls to the supported endpoints. By default, the API server Service deploys at nginx-mesh-api.nginx-mesh.svc/api.

Set up Access to the REST API

To access the Service Mesh API:

1. Run the kubectl port-forward command to expose the Service.

   kubectl port-forward -n nginx-mesh svc/nginx-mesh-api 8443:443
   

2. Send requests to https://localhost:8443.

Command Line Access

The nginx-meshctl command line tool acts as a wrapper around the Service Mesh API. You can use the nginx-meshctl CLI to access the API endpoints, which simplifies human interactions with the REST API. For automation purposes, you can also access the REST API programmatically.

Refer to the CLI documentation for more information on how to use nginx-meshctl.

Programmatic Access

Kubernetes has a variety of proxies, any of which can access the NGINX Service Mesh API.

For programmatic access, we recommend using a Kubernetes client SDK and using a working kubeconfig file, as in many cases you may use a mix of kubectl and Service Mesh API calls.

Secure Communication

If you deployed the mesh with an upstream certificate and key, then you should use that cert and key to securely connect to the API server. For example:

curl --cacert /path/to/cert ...

In all other cases, the API server uses a self-signed cert and key. In this case, you will need to use insecure HTTPS to access the API server. For example:

curl -k ...

Example Use Cases

View the Mesh State by using the REST API

You can use the REST API – or, in some cases, the nginx-meshctl command line tool – to view the current state of the mesh.

• View the configuration of the mesh:

  • REST API endpoint: /api/config
  • CLI command: nginx-meshctl config

• View the services participating in the mesh:

  • REST API endpoint: /api/services
  • CLI command: nginx-meshctl services

Modify the Mesh State by using the REST API

NGINX Service Mesh API is under active development, but provides an endpoint and PATCH method to update a subset of the deployment configuration. The API schema is described in the patchConfig section.

You can send a PATCH command to the /api/config endpoint to modify certain configuration options. The supported operations are:

• add
• remove
• replace

There are a subset of fields and objects supported for add, remove, and replace. Refer to the PATCH config schema described above for the full reference, the following examples can be referred to for a quick start.

Example: Disable Automatic injection in All Namespaces

The payload shown below disables automatic injection of the sidecar proxy for all namespaces and enables it for only the “prod” and “staging” namespaces.

[
    {
        "op": "replace",
        "field": {
            "injection": {
                "isAutoInjectEnabled": false
            }
        }
    },
    {
        "op": "add",
        "field": {
            "injection": {
                "enabledNamespaces": ["prod", "staging"]
            }
        }
    }
]

or

{
    "op": "replace",
    "field": {
        "injection": {
            "isAutoInjectEnabled": false,
            "enabledNamespaces": ["default", "my-namespace"]
        }
    }
}

To remove all values from a list of strings, define the value as an empty list (using replace with an empty list will have the same effect). For example:

{
    "op": "remove",
    "field": {
        "injection": {
            "enabledNamespaces": []
        }
    }
}

Inject the Sidecar Proxy into Kubernetes Resources

You can use the CLI or the REST API to manually inject the sidecar proxy into a Kubernetes resource definition.

• CLI command: nginx-meshctl inject
• API endpoint: /api/inject

The NGINX Service Mesh supports injection for the following Kubernetes resources:

• Deployment
• DaemonSet
• StatefulSet
• ReplicaSet
• ReplicationController
• Job
• Pod

Requests to the /api/inject endpoint must include the following:

• Content-Type: multipart/form-data header

• a JSON or YAML file sent as a form field with a key name of file and the Content-Type: octet-stream header.

  Usage: -F file=@my-app.json

The endpoint also supports the following optional form fields:

• ignoreIncomingPorts: a string list of ports for the proxy to ignore for incoming traffic; with Content-Type: text/plain.

  Usage: -F "ignoreIncomingPorts=80;type=text/plain"

• ignoreOutgoingPorts: a string list of ports for the proxy to ignore for outgoing traffic; with Content-Type: text/plain.

  Usage: -F "ignoreOutgoingPorts=90;type=text/plain"

Example CURL Requests for Sidecar Proxy Injection

• Provide a JSON file for injection:

  curl -vvv -X POST -H "Content-Type:multipart/form-data" https://nginx-mesh-api/api/inject -F file=@my-app.json
  

• Provide a YAML file, ignore incoming requests for port 80, and ignore outgoing traffic on port 90:

  curl -vvv -X POST -H "Content-Type:multipart/form-data" https://nginx-mesh-api/api/inject -F file=@my-app.yaml
  -F "ignoreIncomingPorts=80;type=text/plain" -F "ignoreOutgoingPorts=90;type=text/plain"
  

• Ignore incoming requests on multiple ports (80, 90):

  curl -vvv -X POST -H "Content-Type:multipart/form-data" https://nginx-mesh-api/api/inject -F file=@my-app.yaml
  -F "ignoreIncomingPorts=80;type=text/plain" -F "ignoreIncomingPorts=90;type=text/plain"