Wingman API Reference

Overview

F5 Distributed Cloud Services provides Wingman as a security sidecar for security-related work for workloads. Wingman helps with identity bootstrapping, secrets management, external secret management, certificate rotation, and more.

The sidecar runs in the same pod as the workload. Only the workload can reach it, so it adds no security risk. It prevents applications from handling sensitive material on their own.

To set up Wingman, see the guide.

Note: By default, Wingman isn't injected into customer pods. You can optionally set up Wingman sidecar injection if you need Distributed Cloud secrets management services.

Identity bootstrapping

When a pod starts, Wingman makes API calls to the Identity Service (running in Distributed Cloud Services Global Controller). Wingman fetches the pod identity in the form of x.509 certificates. It writes these certificates in a volume that is shared with all containers in the pod.

Each certificate is pod-specific. It carries identity data such as DNS names and pod labels, plus Distributed Cloud attributes such as tenant and site. 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 decrypts a Blindfold secret. Pass the encrypted secret information in the POST body.

Blindfold secrets

To fetch an encrypted secret using Distributed Cloud Services Secret Management System (Blindfold), the caller must provide the Base64-encoded encrypted bytes in the request body. Upon success, this API returns 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=