Merge branch 'main' into 13498-optimize-8-docker-tag-update

api/console-sm/console-sm-openapi.yaml

@@ -0,0 +1,249 @@
+openapi: 3.0.0
+components:
+  examples: {}
+  headers: {}
+  parameters: {}
+  requestBodies: {}
+  responses: {}
+  schemas:
+    ConsoleSMAdminApi.UsageMetricsInstances:
+      properties:
+        total:
+          type: number
+          format: double
+          description: The number of usage metrics for a specific type.
+      required:
+        - total
+      type: object
+      additionalProperties: false
+    ConsoleSMAdminApi.UsageMetricsTaskUsers:
+      properties:
+        total:
+          type: number
+          format: double
+          description: The number of usage metrics for a specific type.
+        assignees:
+          items:
+            type: string
+          type: array
+          description: The users that tasks have been assigned to.
+      required:
+        - total
+        - assignees
+      type: object
+      additionalProperties: false
+    ConsoleSMAdminApi.UsageMetricsForCluster:
+      properties:
+        id:
+          type: string
+          description: The identifier of the cluster.
+        processInstances:
+          $ref: "#/components/schemas/ConsoleSMAdminApi.UsageMetricsInstances"
+          description: The usage metrics for started process instances.
+        decisionInstances:
+          $ref: "#/components/schemas/ConsoleSMAdminApi.UsageMetricsInstances"
+          description: The usage metrics for executed decision instances.
+        taskUsers:
+          $ref: "#/components/schemas/ConsoleSMAdminApi.UsageMetricsTaskUsers"
+          description: The usage metrics for assigned task users.
+      required:
+        - id
+        - processInstances
+        - decisionInstances
+        - taskUsers
+      type: object
+      additionalProperties: false
+    ConsoleSMAdminApi.Status:
+      type: string
+      enum:
+        - healthy
+        - unhealthy
+        - unknown
+    ConsoleSMAdminApi.ClusterType:
+      type: string
+      enum:
+        - automation
+        - management
+    ConsoleSMAdminApi.AppType:
+      type: string
+      enum:
+        - zeebe-broker
+        - zeebe-gateway
+        - operate
+        - tasklist
+        - optimize
+        - modeler
+        - console
+        - identity
+        - unknown
+    ConsoleSMAdminApi.App:
+      properties:
+        type:
+          $ref: "#/components/schemas/ConsoleSMAdminApi.AppType"
+          description:
+            What application is running in the cluster, like Zeebe, Operate,
+            Tasklist, ...
+        id:
+          type: string
+          description: Unique identifier of the application
+        status:
+          $ref: "#/components/schemas/ConsoleSMAdminApi.Status"
+          description: Indicates if an application is healthy or not
+        url:
+          type: string
+          description: The public URL of the application
+        generation:
+          type: string
+          description: This is the current version of the running application
+        readiness:
+          type: string
+          description: The readiness URL of the application
+        metrics:
+          type: string
+          description: The metrics URL of the application
+      required:
+        - type
+        - id
+        - status
+        - url
+        - generation
+      type: object
+      additionalProperties: false
+    ConsoleSMAdminApi.Cluster:
+      properties:
+        uuid:
+          type: string
+          description: Unique identifier of the cluster
+        name:
+          type: string
+          description: Name of the cluster
+        namespace:
+          type: string
+          description: Namespace the cluster is running in.
+        status:
+          $ref: "#/components/schemas/ConsoleSMAdminApi.Status"
+          description: Indicates if a cluster is healthy or not
+        generation:
+          type: string
+          description: This is the current version of the running cluster
+        type:
+          $ref: "#/components/schemas/ConsoleSMAdminApi.ClusterType"
+          description:
+            We're distinguishing between automation and management clusters.
+            Management clusters include applications that act globally in an
+            installed context, like Console or Modeler. Automation clusters are
+            the Zeebe clusters including applications like Operate, Tasklist and
+            Optimize.
+        apps:
+          items:
+            $ref: "#/components/schemas/ConsoleSMAdminApi.App"
+          type: array
+          description: The list of applications running in the cluster
+      required:
+        - uuid
+        - name
+        - namespace
+        - status
+        - generation
+        - type
+        - apps
+      type: object
+      additionalProperties: false
+  securitySchemes:
+    bearer:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+info:
+  title: Console SM Admin API
+  description: Access the administration API of Console SM.
+  version: 1.0.0
+  contact:
+    url: https://www.camunda.com
+  license:
+    name: License
+    url: https://docs.camunda.io/docs/reference/licenses/
+paths:
+  /admin-api/usage-metrics:
+    get:
+      operationId: getUsageMetrics
+      responses:
+        "200":
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ConsoleSMAdminApi.UsageMetricsForCluster"
+        "403":
+          description: Forbidden
+        "500":
+          description: Server-side error
+      description: Returns usage metrics for a specific cluster for a given time
+        range. The usage metrics are aggregated over the time range and include
+        number of started process instances, executed decision instances, and
+        assigned task users.
+      summary: Get usage metrics for clusters
+      tags:
+        - Usage Metrics
+      security:
+        - bearer: []
+      parameters:
+        - description: The unique identifier of the cluster
+          in: query
+          name: id
+          required: true
+          schema:
+            type: string
+        - description:
+            The start timestamp of the time range as UNIX timestamp in
+            milliseconds
+          in: query
+          name: start
+          required: true
+          schema:
+            format: double
+            type: number
+        - description: The end timestamp of the time range as UNIX timestamp in milliseconds
+          in: query
+          name: end
+          required: true
+          schema:
+            format: double
+            type: number
+  /admin-api/clusters:
+    get:
+      operationId: getClusters
+      responses:
+        "200":
+          description: Ok
+          content:
+            application/json:
+              schema:
+                items:
+                  $ref: "#/components/schemas/ConsoleSMAdminApi.Cluster"
+                type: array
+        "403":
+          description: Forbidden
+        "500":
+          description: Server-side error
+      description:
+        Returns a list of all automation and management clusters. Each
+        cluster entry contains the running apps and their status.
+      summary: Get current clusters
+      tags:
+        - Clusters
+      security:
+        - bearer: []
+      parameters: []
+servers:
+  - url: "{schema}://{host}:{port}"
+    variables:
+      host:
+        default: localhost
+        description: The hostname of the API server.
+      port:
+        default: "8080"
+        description: The port of the API server.
+      schema:
+        default: http
+        description: The schema of the API server.

api/console-sm/generation-strategy.js

@@ -0,0 +1,19 @@
+const { makeServerDynamic } = require("../make-server-dynamic");
+const removeDuplicateVersionBadge = require("../remove-duplicate-version-badge");
+
+const outputDir = "docs/apis-tools/console-sm-api/specifications";
+const specFile = "api/console-sm/console-sm-openapi.yaml";
+
+function preGenerateDocs() {
+  makeServerDynamic(specFile);
+}
+
+function postGenerateDocs() {
+  removeDuplicateVersionBadge(`${outputDir}/console-sm-admin-api.info.mdx`);
+}
+
+module.exports = {
+  outputDir,
+  preGenerateDocs,
+  postGenerateDocs,
+};

api/generate-api-docs.js

@@ -4,11 +4,13 @@ const { execSync } = require("child_process");
 const operate = require("./operate/generation-strategy");
 const zeebe = require("./zeebe/generation-strategy");
 const tasklist = require("./tasklist/generation-strategy");
+const consolesm = require("./console-sm/generation-strategy");
 const camunda = require("./camunda/generation-strategy");
 const apiStrategies = {
   operate,
   zeebe,
   tasklist,
+  consolesm,
   camunda,
 };
 

docs/apis-tools/administration-api/authentication.md

@@ -6,17 +6,72 @@ sidebar_position: 2
 description: "Learn about access tokens and client credentials and scopes to get started with the Administration API."
 ---
 
-To access the API endpoint, you need an access token. Your client must send a header in each request:
-
-`Authorization: Bearer <Token>`
-
-For example, send a request using _curl_:
+All Administration API requests require authentication. To authenticate, generate a [JSON Web Token (JWT)](https://jwt.io/introduction/) and pass it in each request.
+
+## Generating a token
+
+1. Create client credentials by clicking **Console > Organization > Administration API > Create new credentials**.
+2. Add permissions to this client for [the needed scopes](#client-credentials-and-scopes).
+3. Upon creating the client, capture the following values required to generate a token:
+   <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 -->
+   | Name                     | Environment variable name        | Default value                                |
+   | ------------------------ | -------------------------------- | -------------------------------------------- |
+   | Client ID                | `CAMUNDA_CONSOLE_CLIENT_ID`      | -                                            |
+   | Client Secret            | `CAMUNDA_CONSOLE_CLIENT_SECRET`  | -                                            |
+   | Authorization Server URL | `CAMUNDA_OAUTH_URL`              | `https://login.cloud.camunda.io/oauth/token` |
+   | Audience                 | `CAMUNDA_CONSOLE_OAUTH_AUDIENCE` | `api.cloud.camunda.io`                       |
+   <!-- this comment convinces the markdown processor to still treat the table as a table, but without adding surrounding paragraphs. 🤷 -->
+   :::tip
+   When client credentials are created, the `Client Secret` is only shown once. Save this `Client Secret` somewhere safe.
+   :::
+4. Execute an authentication request to the token issuer:
+   ```bash
+   curl --request POST ${CAMUNDA_OAUTH_URL} \
+       --header 'Content-Type: application/x-www-form-urlencoded' \
+       --data-urlencode 'grant_type=client_credentials' \
+       --data-urlencode "audience=${CAMUNDA_CONSOLE_OAUTH_AUDIENCE}" \
+       --data-urlencode "client_id=${CAMUNDA_CONSOLE_CLIENT_ID}" \
+       --data-urlencode "client_secret=${CAMUNDA_CONSOLE_CLIENT_SECRET}"
+   ```
+5. A successful authentication response looks like the following:
+   ```json
+   {
+     "access_token": "<TOKEN>",
+     "expires_in": 300,
+     "refresh_expires_in": 0,
+     "token_type": "Bearer",
+     "not-before-policy": 0
+   }
+   ```
+6. Capture the value of the `access_token` property and store it as your token.
+
+## Using a token
+
+Include the captured token as an authorization header in each request: `Authorization: Bearer <TOKEN>`.
+
+For example, to call the Administration API's `/members` endpoint, send the following request:
 
 ```shell
-curl -X POST -H -H :accept: application/json" -H "Authorization: Bearer <TOKEN>" -d '' http://api.cloud.camunda.io/clusters
+curl --header "Authorization: Bearer ${TOKEN}" \
+     https://api.cloud.camunda.io/members
+```
+
+A successful response would include [a list of organization members](https://console.cloud.camunda.io/customer-api/openapi/docs/#/default/GetMembers). For example:
+
+```json
+[
+  {
+    "name": "User Userton",
+    "email": "[email protected]",
+    "roles": ["admin"],
+    "invitePending": false
+  }
+]
 ```
 
-For all requests, include the access token in the authorization header: `authorization:Bearer ${TOKEN}`.
+## Token expiration
+
+Access tokens expire according to the `expires_in` property of a successful authentication response. After this duration, in seconds, you must request a new access token.
 
 ## Client credentials and scopes
 
@@ -40,25 +95,6 @@ A client can have one or multiple permissions from the following groups:
 
 The full API description can be found [here](https://console.cloud.camunda.io/customer-api/openapi/docs/#/).
 
-:::note
-After client credentials are created, the `Client Secret` is only shown once. Save this `Client Secret` somewhere safe.
-:::
-
-## Access token
-
-Once you have your client credentials, you can retrieve an access token using the following command:
-
-```bash
-curl --header "Content-Type: application/json" \
-    --request POST \
-    --data '{"grant_type":"client_credentials", "audience":"api.cloud.camunda.io", "client_id":"XXX", "client_secret":"YYY"}' \
-    https://login.cloud.camunda.io/oauth/token
-```
-
-:::note
-Access tokens have a validity period found in the access token. After this time, a new access token must be requested.
-:::
-
 ## Rate limiting
 
 The OAuth service rate limits about one request per second for all clients with the same source IP address.