Lieutenant API

Abstract
Project Syn Management API

1. Access

  • Bearer Authentication

2. Endpoints

2.1. Bootstrapping

2.1.1. installSteward

GET /install/steward.json

Returns the Steward JSON installation manifest

Description

Autogenerated JSON containing all the needed parameters for having Steward up and running. It Iterates through all available Cluster objects to find the object matching the token in the field spec.bootstrapToken.token. It checks if the token is valid (fields spec.bootstrapToken.valid and field spec.bootstrapToken.validUntil). If valid delivers the JSON and sets the field spec.bootstrapToken.valid to false.

Parameters
Query Parameters
Name Description Required Default Pattern

token

Initial bootstrap token

-

null
Return Type

[Object]

Content Type

  • application/json

Responses
Table 1. http response codes
Code Message Datatype

200

Kubernetes manifests to install Steward, the cluster agent

[Object]

401

Token invalid

<<>>

404

Cluster not found

<<>>

0

A default response with a reason.

Reason
Samples

2.2. Cluster

2.2.1. createCluster

POST /clusters

Creates a new cluster

Description

Create a cluster in the API. The ID is generated by the API (in the form c-<adjective>-<noun>-<digits> where all the words are lowercase, max 63 characters in total). It checks if the tenant exists before creating the object, otherwise fails. It generates the Cluster object and its <GitRepoSpec> and bootstrapToken values.

Parameters
Body Parameter
Name Description Required Default Pattern

Cluster

Create a new Cluster Cluster

X
Return Type

Cluster

Content Type

  • application/json

Responses
Table 2. http response codes
Code Message Datatype

201

Cluster created

Cluster

400

Cluster can't be created

Reason

405

Cluster already exists

<<>>

0

A default response with a reason.

Reason
Samples

2.2.2. deleteCluster

DELETE /clusters/{clusterId}

Deletes a cluster

Description

Deletes a cluster

Parameters
Path Parameters
Name Description Required Default Pattern

clusterId

Distinct id of the cluster.

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 3. http response codes
Code Message Datatype

204

Cluster deleted

<<>>

403

Cluster deletion forbidden

Reason

0

A default response with a reason.

Reason
Samples

2.2.3. getCluster

GET /clusters/{clusterId}

Returns all values of a cluster

Description

Returns all values of a cluster

Parameters
Path Parameters
Name Description Required Default Pattern

clusterId

Distinct id of the cluster.

X

null
Return Type

Cluster

Content Type

  • application/json

Responses
Table 4. http response codes
Code Message Datatype

200

Cluster found

Cluster

404

A cluster with the specified id wasn't found.

<<>>

0

A default response with a reason.

Reason
Samples

2.2.4. listClusters

GET /clusters

Returns a list of clusters

Description

List of clusters available in the API

Parameters
Query Parameters
Name Description Required Default Pattern

tenant

Filter clusters by tenant id

-

null
Return Type

array[Cluster]

Content Type

  • application/json

Responses
Table 5. http response codes
Code Message Datatype

200

Cluster listing. Empty array if no tenants available.

List[Cluster]

0

A default response with a reason.

Reason
Samples

2.2.5. updateCluster

PATCH /clusters/{clusterId}

Updates a cluster

Description

Updates a cluster

Parameters
Path Parameters
Name Description Required Default Pattern

clusterId

Distinct id of the cluster.

X

null
Body Parameter
Name Description Required Default Pattern

ClusterProperties

Update cluster with properties to be changed (RFC 7396) ClusterProperties

X
Return Type

Cluster

Content Type

  • application/json

Responses
Table 6. http response codes
Code Message Datatype

200

Cluster updated

Cluster

403

Cluster update forbidden

Reason

0

A default response with a reason.

Reason
Samples

2.3. Inventory

2.3.1. queryInventory

GET /inventory

Returns inventory data according to query

Description

Search inventory data

Parameters
Query Parameters
Name Description Required Default Pattern

q

InfluxQL query string

-

null
Return Type

Inventory

Content Type

  • application/json

Responses
Table 7. http response codes
Code Message Datatype

200

Query succeeded

Inventory

0

A default response with a reason.

Reason
Samples

2.3.2. updateInventory

POST /inventory

Write inventory data

Description

Write inventory data

Parameters
Body Parameter
Name Description Required Default Pattern

Inventory

Inventory data of a cluster Inventory

X
Return Type

-

Content Type

  • application/json

Responses
Table 8. http response codes
Code Message Datatype

201

Inventory data stored

<<>>

0

A default response with a reason.

Reason
Samples

2.4. System

2.4.1. docs

GET /docs

API documentation

Description

Interactive API documentation based on Swagger UI

Parameters
Return Type

[String]

Content Type

  • text/html

Responses
Table 9. http response codes
Code Message Datatype

200

Swagger UI assets

[String]
Samples

2.4.2. healthz

GET /healthz

API health check

Description

API health check

Parameters
Return Type

[String]

Content Type

  • text/plain

  • application/json

Responses
Table 10. http response codes
Code Message Datatype

200

All is fine

[String]

0

A default response with a reason.

Reason
Samples

2.4.3. openapi

GET /openapi.json

OpenAPI JSON spec

Description

OpenAPI JSON specification

Parameters
Return Type

[Object]

Content Type

  • application/json

Responses
Table 11. http response codes
Code Message Datatype

200

OpenAPI JSON spec

[Object]
Samples

2.5. Tenant

2.5.1. createTenant

POST /tenants

Creates a new tenant

Description

Create a tenant in the API. The ID is generated by the API (in the form t-<adjective>-<noun>-<digits> where all the words are lowercase, max 63 characters in total). It generates the Tenant object in the configured namespace (usually the same namespace where the API runs). The customer config Git repository URL is required.

Parameters
Body Parameter
Name Description Required Default Pattern

Tenant

Create a new tenant Tenant

X
Return Type

Tenant

Content Type

  • application/json

Responses
Table 12. http response codes
Code Message Datatype

201

Tenant created

Tenant

400

Tenant can't be created

Reason

405

Tenant already exists

<<>>

0

A default response with a reason.

Reason
Samples

2.5.2. deleteTenant

DELETE /tenants/{tenantId}

Deletes a tenant

Description

Deletes a tenant

Parameters
Path Parameters
Name Description Required Default Pattern

tenantId

Distinct id of the tenant.

X

null
Return Type

-

Content Type

  • application/json

Responses
Table 13. http response codes
Code Message Datatype

204

Tenant deleted

<<>>

403

Tenant deletion forbidden

Reason

0

A default response with a reason.

Reason
Samples

2.5.3. getTenant

GET /tenants/{tenantId}

Returns all values of a tenant

Description

Returns all values of a tenant

Parameters
Path Parameters
Name Description Required Default Pattern

tenantId

Distinct id of the tenant.

X

null
Return Type

Tenant

Content Type

  • application/json

Responses
Table 14. http response codes
Code Message Datatype

200

Tenant found

Tenant

404

A tenant with the specified id wasn't found.

<<>>

0

A default response with a reason.

Reason
Samples

2.5.4. listTenants

GET /tenants

Returns a list of tenants

Description

List of all tenants available in the API

Parameters
Return Type

array[Tenant]

Content Type

  • application/json

Responses
Table 15. http response codes
Code Message Datatype

200

Tenant listing. Empty array if no tenants available.

List[Tenant]

0

A default response with a reason.

Reason
Samples

2.5.5. updateTenant

PATCH /tenants/{tenantId}

Updates a tenant

Description

Updates a tenant

Parameters
Path Parameters
Name Description Required Default Pattern

tenantId

Distinct id of the tenant.

X

null
Body Parameter
Name Description Required Default Pattern

TenantProperties

Update tenant with properties to be changed (RFC 7396) TenantProperties

X
Return Type

Tenant

Content Type

  • application/json

Responses
Table 16. http response codes
Code Message Datatype

200

Tenant updated

Tenant

403

Tenant update forbidden

Reason

0

A default response with a reason.

Reason
Samples

3. Models

3.1. Cluster

Field Name Required Type Description Format

id

X

String

A unique object identifier string. Automatically generated by the API on creation (in the form &quot;<letter>-<adjective>-<noun>-<digits>&quot; where all letters are lowercase, max 63 characters in total).

tenant

X

String

Id of the tenant this cluster belongs to

annotations

Object

Unstructured key value map containing arbitrary metadata

displayName

String

Display Name of the cluster

facts

Object

Facts about a cluster object. Statically configured key/value pairs.

gitRepo

GitRepo

tenantGitRepoRevision

String

Git revision to use with the tenant configruation git repository. This takes precedence over the revision configured on the Tenant.

globalGitRepoRevision

String

Git revision to use with the global configruation git repository. This takes precedence over the revision configured on the Tenant.

installURL

String

URL to fetch install manifests for Steward cluster agent. This will only be set if the cluster's token is still valid.

3.2. ClusterId

Field Name Required Type Description Format

id

X

String

A unique object identifier string. Automatically generated by the API on creation (in the form &quot;<letter>-<adjective>-<noun>-<digits>&quot; where all letters are lowercase, max 63 characters in total).

3.3. ClusterProperties

A cluster defition object. The Git repository is usually managed by the API and autogenerated. The sshDeployKey will be managed by Steward

Field Name Required Type Description Format

annotations

Object

Unstructured key value map containing arbitrary metadata

displayName

String

Display Name of the cluster

facts

Object

Facts about a cluster object. Statically configured key/value pairs.

gitRepo

GitRepo

tenantGitRepoRevision

String

Git revision to use with the tenant configruation git repository. This takes precedence over the revision configured on the Tenant.

globalGitRepoRevision

String

Git revision to use with the global configruation git repository. This takes precedence over the revision configured on the Tenant.

installURL

String

URL to fetch install manifests for Steward cluster agent. This will only be set if the cluster's token is still valid.

3.4. ClusterTenant

Field Name Required Type Description Format

tenant

X

String

Id of the tenant this cluster belongs to

3.5. CreateCluster

Field Name Required Type Description Format

tenant

X

String

Id of the tenant this cluster belongs to

annotations

Object

Unstructured key value map containing arbitrary metadata

displayName

String

Display Name of the cluster

facts

Object

Facts about a cluster object. Statically configured key/value pairs.

gitRepo

GitRepo

tenantGitRepoRevision

String

Git revision to use with the tenant configruation git repository. This takes precedence over the revision configured on the Tenant.

globalGitRepoRevision

String

Git revision to use with the global configruation git repository. This takes precedence over the revision configured on the Tenant.

installURL

String

URL to fetch install manifests for Steward cluster agent. This will only be set if the cluster's token is still valid.

3.6. GitRepo

Configuration Git repository, usually generated by the API

Field Name Required Type Description Format

url

String

Full URL of the git repo

type

String

Specifies if a repo should be managed by the git controller. A value of 'unmanaged' means it's not manged by the controller

deployKey

String

SSH public key / deploy key for clusterconfiguration catalog Git repository. This property is managed by Steward.

hostKeys

String

SSH known hosts of the git server (multiline possible for multiple keys)

3.7. Inventory

Inventory data of a cluster

Field Name Required Type Description Format

cluster

X

String

inventory

Object

3.8. Reason

A reason for responses

Field Name Required Type Description Format

reason

X

String

The reason message

3.9. Revision

Field Name Required Type Description Format

revision

String

Revision to use with a git repository.

3.10. RevisionedGitRepo

Field Name Required Type Description Format

url

String

Full URL of the git repo

type

String

Specifies if a repo should be managed by the git controller. A value of 'unmanaged' means it's not manged by the controller

deployKey

String

SSH public key / deploy key for clusterconfiguration catalog Git repository. This property is managed by Steward.

hostKeys

String

SSH known hosts of the git server (multiline possible for multiple keys)

revision

String

Revision to use with a git repository.

3.11. Tenant

Field Name Required Type Description Format

id

X

String

A unique object identifier string. Automatically generated by the API on creation (in the form &quot;<letter>-<adjective>-<noun>-<digits>&quot; where all letters are lowercase, max 63 characters in total).

annotations

Object

Unstructured key value map containing arbitrary metadata

displayName

String

Display name of the tenant

gitRepo

RevisionedGitRepo

globalGitRepoURL

String

Full URL of the global configuration git repo

globalGitRepoRevision

String

Git revision to use with the global configruation git repository.

3.12. TenantId

Field Name Required Type Description Format

id

X

String

A unique object identifier string. Automatically generated by the API on creation (in the form &quot;<letter>-<adjective>-<noun>-<digits>&quot; where all letters are lowercase, max 63 characters in total).

3.13. TenantProperties

A tenant definition object. The Git repository is usually managed by the API and autogenerated. All properties except name are optional on creation.

Field Name Required Type Description Format

annotations

Object

Unstructured key value map containing arbitrary metadata

displayName

String

Display name of the tenant

gitRepo

RevisionedGitRepo

globalGitRepoURL

String

Full URL of the global configuration git repo

globalGitRepoRevision

String

Git revision to use with the global configruation git repository.