Wingman API Reference

Overview

Wingman is a security sidecar provided by F5® Distributed Cloud Services that does most of the security-related work for the workload from identity bootstrapping, secrets management, external secrets' management, certificate rotation, etc.

Every customer workload is automatically injected with this sidecar, and it acts as an assistant to the customer workload. Since the sidecar executes within the same security boundary (Pod) as the workload and is only accessible by the workload, no security risk is added; in fact, it prevents applications from handling sensitive material on their own.

Bootstrapped Identity

When a Pod is launched, Wingman makes API calls to the Identity Service (running in Distributed Cloud Services Global Controller) and fetches Pod Identity in the form of x.509 certificates. Wingman writes these certificates in a volume mounted at /volterra/secrets/identity that is shared with all containers in the Pod.

Upon successful retrieval of the certificates, the content of the directory will look like this:

$ ls -lart /volterra/secrets/identity
-rwxr-xr-x    1 root     root          1679 Feb  4 21:26 server.key
-rwxr-xr-x    1 root     root          6652 Feb  4 21:26 server.crt
-rwxr-xr-x    1 root     root          2171 Feb  4 21:26 client_ca.crt
-rwxr-xr-x    1 root     root          1675 Feb  4 21:26 client.key
-rwxr-xr-x    1 root     root          6648 Feb  4 21:26 client.crt
-rwxr-xr-x    1 root     root          2171 Feb  4 21:26 server_ca.crt

The client.crt and server.crt certificates are pod-specific certificates and contain identity information, like DNS names, pod labels, and other Distributed Cloud Services-specific information (like tenant, site, etc.). These identities are recognized across all the vK8s clusters for the tenant.

Wingman APIs

Wingman also starts an HTTP server at http://localhost:8070 in the application Pod. Wingman exposes APIs in the following three categories:

• Status API: To get the status of Wingman
• Identity APIs: To get certificates/keys/CA-Certificates
• Secret Management APIs: To decrypt secrets

Status API

GET /status

Returns current state of the Wingman. Wingman can return one of the following states:

• INITIALIZING: Wingman is still initializing and does not have identity certificates.

• READY: Wingman has the identity and is ready to serve.

• DEGRADED: Wingman identity certs are about to expire but the last attempt to renew failed.

• HALTED: Wingman was not able to fetch identity certs and is not able to serve anymore.

For example:

$ curl http://localhost:8070/status
READY

Note: /status API always returns response code 200 and only fails if Wingman is not up or reachable.

Identity APIs

GET /creds/pki/server/key

Returns the private key of the server certificate in PEM format.

GET /creds/pki/server/cert

Returns the server certificate chain in PEM format.

GET /creds/pki/server/cert-only

Returns the server certificate (only leaf) in PEM format.

GET /creds/pki/client/key

Returns the private key of the client certificate in PEM format.

GET /creds/pki/client/cert

Returns the client certificate chain in PEM format.

GET /creds/pki/client/cert-only

Returns the client certificate (only leaf) in PEM format.

GET /trust/pki/{ca_bundle_name}

Returns the CA certificates for the CA bundle ca_bundle_name. Currently, the following ca_bundle_name certificates are valid:

• server_ca: Returns CA certificates used to trust remote servers running in the vk8s cluster.
• client_ca: Returns CA certificates used to trust remote clients running in the vk8s cluster.

Secret Management API

POST /secret/unseal

This endpoint is used for decrypting Blindfold secret. The encrypted secret information needs to be passed as POST body.

Blindfold secrets

For fetching a secret encrypted using Distributed Cloud Services Secret Management System (Blindfold), the caller needs to provide Base64 Encoded Encrypted Bytes in the request body. Upon success, this API will return Base64 encoded decrypted bytes.

The request body has the following schema:

{
  "type": "blindfold",
  // Secret location
  // It must be in url format string:///
  "location": <secret_url>
}

The potential responses include the following:

For example:

$ cat request.json
{
  "type": "blindfold",
  "location": "string:///AAAACWN1c3RvbWVyMQAAAAEAAAAAAAAAiAIAAAAFA6ur/XkAAAEArc3DxZa69sWeIn9NRrHGcZlZaXLHWYjc57jIS76Z47AcU0jDmodz3lNEysVO2swNAUn8p6yiuvf8Vj4LUuWB++LdP2yYX5ftEHmMgnHTaTeW0or87X24nK4UPollx/2S9/i+tJN9VcrhCFWYHMMPx9AU7Lw7yJ7CPuv7x5EJZl/BOonWhYst1d7fb6GPMSxhqsxoR2i8aDkl1sMCaFbBv1oANfDrL1DrXnae7iXuZPGzxszeDWlZakvwek3lsWMJT4b2rhjXML2Vq4AdKFBp5zbrh15g7mS0lpdX/xG6h0+IdHyrWPoIg/hZwYyV9xmIOcFc1Jk5PZC554hchHbToQAAAQCKnfbK+kRkQDOOFC6WWHtha8DacIOY25GO5wEO58bYkeXYmtbEBfExvpE7yNndKDlKSWLHVBdS2jqVXzAYD2A4EzmZmWyo7RyCjSclbm/fSaVTN0BFI7kHllcbg6df4BuXlN6CZ2ulh0Y8qGeNGwKUQl215CYjjyX5w0ZUjbgse5nHtC0PhWV8XU7cWwtJBhziIdeQHNHvF44txeIcAhOH7DqfqVVQbq77JUm82B3e66+evUqSSb3HYWbySicv1vog/HQyFSStE3BP8q9mQxkyovY489iTiZEj7iKH3951F44waPH5GwsEB+vztkKLm59c/OaM6aVJuWazQUHsSzRBP/SWxd3/i7ATIsCeDDJW2kc578wsJ45E9G2J5o8sMVL5pTlO9Swp9V85DvQMbeeZiKNj"
}

$ curl http://localhost:8070/secret/unseal -X POST -H 'content-type: application/json' -d @request.json
VGhpcyBzZWNyZXQgaXMgZm9yIGRlbW8tdGxzLXNlcnZlcgo=

Concepts

• System Overview
• Core Concepts
• Wingman