From 12e2ff9c4c779bb33ec86ce954253aecb19c9d12 Mon Sep 17 00:00:00 2001 From: kamal-devtron Date: Wed, 23 Jul 2025 13:05:55 +0530 Subject: [PATCH 1/4] added version yml --- specs/swagger/openapi.yaml | 99 +++++++++++++++++++++++++++----------- specs/version.yml | 4 ++ 2 files changed, 74 insertions(+), 29 deletions(-) diff --git a/specs/swagger/openapi.yaml b/specs/swagger/openapi.yaml index da87266b2e..3ec92c3ab8 100644 --- a/specs/swagger/openapi.yaml +++ b/specs/swagger/openapi.yaml @@ -57,15 +57,21 @@ tags: x-displayName: K8s Resource - name: Workflow Management x-displayName: Workflow Management + - name: Devtron Server version + x-displayName: Devtron Server version paths: /app/labels/list: get: summary: List Application Labels - description: | + description: > Retrieves a list of application labels. By default, returns all labels. - Use the `showPropagatedOnly` parameter to filter for labels where propagate = true. - + + Use the `showPropagatedOnly` parameter to filter for labels where + propagate = true. + + **Required Token Permission:** + - Must have **View** access to the applications in scope. operationId: getAppLabels tags: @@ -99,7 +105,7 @@ paths: status: type: string description: Response status message - example: "OK" + example: OK result: type: array description: Array of label objects @@ -115,11 +121,11 @@ paths: key: type: string description: The label key/name - example: "environment" + example: environment value: type: string description: The label value - example: "production" + example: production propagate: type: boolean description: Whether this label should be propagated @@ -131,37 +137,39 @@ paths: appName: type: string description: The name of the application - example: "web-service" + example: web-service examples: all_labels: summary: All labels response - description: Example response when showPropagatedOnly is false or not provided + description: >- + Example response when showPropagatedOnly is false or not + provided value: code: 200 - status: "OK" + status: OK result: - - key: "environment" - value: "production" + - key: environment + value: production propagate: true appId: 1234 - appName: "web-service" - - key: "team" - value: "backend" + appName: web-service + - key: team + value: backend propagate: false appId: 1234 - appName: "web-service" + appName: web-service propagated_only: summary: Propagated labels only description: Example response when showPropagatedOnly is true value: code: 200 - status: "OK" + status: OK result: - - key: "environment" - value: "production" + - key: environment + value: production propagate: true appId: 1234 - appName: "web-service" + appName: web-service '401': description: Authentication required or token invalid content: @@ -174,10 +182,10 @@ paths: example: 401 status: type: string - example: "Unauthorized" + example: Unauthorized message: type: string - example: "Authentication token is required" + example: Authentication token is required '403': description: Insufficient permissions to access the resource content: @@ -190,10 +198,12 @@ paths: example: 403 status: type: string - example: "Forbidden" + example: Forbidden message: type: string - example: "Token does not have View access to the applications in scope" + example: >- + Token does not have View access to the applications in + scope '500': description: Internal server error content: @@ -206,10 +216,10 @@ paths: example: 500 status: type: string - example: "Internal Server Error" + example: Internal Server Error message: type: string - example: "An unexpected error occurred" + example: An unexpected error occurred /batch/{apiVersion}/{kind}/readme: get: summary: Get Readme for Bulk Update @@ -2543,6 +2553,36 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' + /orchestrator/version: + get: + summary: Get Devtron server version information + security: [] + responses: + '200': + description: meta info about devtron server + content: + application/json: + schema: + type: object + properties: + gitCommit: + type: string + example: d252aa3e + description: git hash from which code was compiled + buildTime: + type: string + format: date-time + example: '2021-12-15T05:44:05Z' + description: time when code was complied + serverMode: + type: string + example: FULL + description: server mode FULL/EA_ONLY + enum: + - FULL + - EA_ONLY + tags: + - Devtron Server version components: schemas: BulkUpdateSeeExampleResponse: @@ -2913,8 +2953,8 @@ components: config: type: object description: >- - Configuration for the SSO provider (Dex connector config). - Structure varies. + Configuration for the SSO provider (Dex connector config). Structure + varies. active: type: boolean required: @@ -4203,7 +4243,7 @@ components: name: X-API-Key description: API key authentication x-tagGroups: - - name: Devtron Labs Kubernetes API + - name: Common Devtron automation APIs tags: - Labels - bulk_other @@ -4221,4 +4261,5 @@ x-tagGroups: - Change Chart - Clone Workflow - K8s Resource - - Workflow Management \ No newline at end of file + - Workflow Management + - Devtron Server version diff --git a/specs/version.yml b/specs/version.yml index 0d989f3cfd..74f7d20efc 100644 --- a/specs/version.yml +++ b/specs/version.yml @@ -2,9 +2,13 @@ openapi: "3.0.2" info: title: version api version: "1.0" +servers: + - url: https://example.com/api paths: /orchestrator/version: get: + summary: Get Devtron server version information + security: [] responses: "200": description: meta info about devtron server From 26e49f71723babb1c2f5ae99814a9ec0fab3ac8d Mon Sep 17 00:00:00 2001 From: kamal-devtron Date: Wed, 23 Jul 2025 13:23:42 +0530 Subject: [PATCH 2/4] changes in openapi.yaml --- specs/swagger/openapi.yaml | 48 +++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/specs/swagger/openapi.yaml b/specs/swagger/openapi.yaml index 3ec92c3ab8..daf9095a33 100644 --- a/specs/swagger/openapi.yaml +++ b/specs/swagger/openapi.yaml @@ -1477,7 +1477,7 @@ paths: security: - bearerAuth: [] - apiKeyAuth: [] - /orchestrator/env: + /env: post: summary: Create Environment description: Create a new environment within a cluster. @@ -1607,7 +1607,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /orchestrator/cluster/delete: + /cluster/delete: post: summary: Delete Cluster description: Delete an existing cluster. @@ -1655,7 +1655,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /orchestrator/env/delete: + /env/delete: post: summary: Delete Environment (via POST) description: Delete an existing environment using POST method. @@ -1703,7 +1703,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /orchestrator/env/clusters: + /env/clusters: get: summary: List clusters with their environments description: Provides a list of all clusters and the environments within each. @@ -1734,7 +1734,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /orchestrator/cluster/{cluster_id}/env: + /cluster/{cluster_id}/env: get: summary: List environments for a specific cluster description: Provides a list of all environments for a given cluster ID. @@ -1784,7 +1784,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /orchestrator/cluster: + /cluster: put: summary: Update Cluster description: Update an existing cluster's configuration. @@ -1867,7 +1867,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /orchestrator/cluster/auth-list: + /cluster/auth-list: get: summary: List Accessible Clusters description: list of clusters accessible to the authenticated user. @@ -1902,7 +1902,7 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse' - /orchestrator/cluster/validate: + /cluster/validate: post: summary: Validate Cluster Configuration description: Validate a cluster configuration using kubeconfig. @@ -1941,7 +1941,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /orchestrator/cluster/saveClusters: + /cluster/saveClusters: post: summary: Save Multiple Clusters description: Save configurations for multiple clusters. @@ -1979,7 +1979,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /orchestrator/app/env/patch: + /app/env/patch: patch: summary: Patch Application Environment description: change the deployment template for an app and environment @@ -2005,7 +2005,7 @@ paths: description: bad request tags: - Change Chart - /orchestrator/app/workflow/clone: + /app/workflow/clone: post: summary: Clone Application Workflow description: >- @@ -2031,7 +2031,7 @@ paths: $ref: '#/components/schemas/StandardResponse' tags: - Clone Workflow - /orchestrator/k8s/resource: + /k8s/resource: post: summary: Get Resource Manifest description: >- @@ -2100,7 +2100,7 @@ paths: $ref: '#/components/schemas/ResourceGetResponse' tags: - K8s Resource - /orchestrator/k8s/resource/create: + /k8s/resource/create: post: summary: Create Resource description: >- @@ -2135,7 +2135,7 @@ paths: $ref: '#/components/schemas/ResourceGetResponse' tags: - K8s Resource - /orchestrator/k8s/resource/delete: + /k8s/resource/delete: post: summary: Delete Resource description: This API is used for deleting a specified Kubernetes resource. @@ -2168,7 +2168,7 @@ paths: $ref: '#/components/schemas/ResourceGetResponse' tags: - K8s Resource - /orchestrator/k8s/events: + /k8s/events: post: summary: Get Resource Events description: This API is used for fetching events for Kubernetes resources. @@ -2193,7 +2193,7 @@ paths: $ref: '#/components/schemas/EventsResponseObject' tags: - K8s Resource - /orchestrator/k8s/pods/logs/{podName}: + /k8s/pods/logs/{podName}: get: summary: Get Pod Logs description: >- @@ -2263,7 +2263,7 @@ paths: $ref: '#/components/schemas/LogsResponseObject' tags: - K8s Resource - /orchestrator/k8s/pod/exec/session/{identifier}/{namespace}/{pod}/{shell}/{container}: + /k8s/pod/exec/session/{identifier}/{namespace}/{pod}/{shell}/{container}: get: summary: Get Pod Exec Session description: >- @@ -2322,7 +2322,7 @@ paths: $ref: '#/components/schemas/TerminalMessage' tags: - K8s Resource - /orchestrator/k8s/api-resources/{clusterId}: + /k8s/api-resources/{clusterId}: get: summary: Get API Resources description: Get all available API resources for a given cluster ID. @@ -2347,7 +2347,7 @@ paths: $ref: '#/components/schemas/GetAllApiResourcesResponse' tags: - K8s Resource - /orchestrator/k8s/resource/list: + /k8s/resource/list: post: summary: List Resources description: >- @@ -2385,7 +2385,7 @@ paths: $ref: '#/components/schemas/ClusterResourceListResponse' tags: - K8s Resource - /orchestrator/k8s/resources/rotate: + /k8s/resources/rotate: post: summary: Rotates the Pods description: This API is used to rotate (restart) pods for the provided resources. @@ -2418,7 +2418,7 @@ paths: $ref: '#/components/schemas/RotatePodResponse' tags: - K8s Resource - /orchestrator/k8s/resources/apply: + /k8s/resources/apply: post: summary: Apply Resources description: >- @@ -2448,7 +2448,7 @@ paths: $ref: '#/components/schemas/ApplyResourcesResponse' tags: - K8s Resource - /orchestrator/app/workflow: + /app/workflow: post: summary: Create an application workflow description: Creates a new workflow for a given application. @@ -2495,7 +2495,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /orchestrator/app/workflow/{app-wf-id}/app/{app-id}: + /app/workflow/{app-wf-id}/app/{app-id}: delete: summary: Delete an application workflow description: Deletes an existing workflow for a given application. @@ -2553,7 +2553,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /orchestrator/version: + /version: get: summary: Get Devtron server version information security: [] From fb4aeb1770fb6115bcf32b43377bcb95f92e31d5 Mon Sep 17 00:00:00 2001 From: kamal-devtron Date: Wed, 23 Jul 2025 15:46:56 +0530 Subject: [PATCH 3/4] added gitops validation api spec --- specs/gitops-validation.yaml | 16 +++- specs/swagger/openapi.yaml | 181 +++++++++++++++++++++++++++++++++++ 2 files changed, 196 insertions(+), 1 deletion(-) diff --git a/specs/gitops-validation.yaml b/specs/gitops-validation.yaml index 0a3a5ad68c..ff912bd48f 100644 --- a/specs/gitops-validation.yaml +++ b/specs/gitops-validation.yaml @@ -3,11 +3,14 @@ info: version: 1.0.0 title: GitOps Validation servers: - - url: http://localhost:3000/orchestrator/gitops + - url: https://api.yourdomain.com paths: /validate: post: description: Validate gitops configuration by dry run + summary: Validate gitops configuration by dry run + security: + - ApiKeyAuth: [] operationId: GitOpsValidateDryRun requestBody: description: A JSON object containing the gitops configuration @@ -44,6 +47,9 @@ paths: /config: post: description: create/save new configuration and validate them before saving + summary: create/save new configuration and validate them before saving + security: + - ApiKeyAuth: [] operationId: CreateGitOpsConfig requestBody: description: A JSON object containing the gitops configuration @@ -79,7 +85,10 @@ paths: $ref: '#/components/schemas/Error' put: description: update configuration and validate them before saving(if last validation is within 30 seconds then do not validate) + summary: update configuration and validate them before saving(if last validation is within 30 seconds then do not validate) operationId: UpdateGitOpsConfig + security: + - ApiKeyAuth: [] requestBody: description: A JSON object containing the gitops configuration required: true @@ -114,6 +123,11 @@ paths: $ref: '#/components/schemas/Error' components: + securitySchemes: + ApiKeyAuth: + type: apiKey + in: header + name: Authorization schemas: GitOpsConfigDto: type: object diff --git a/specs/swagger/openapi.yaml b/specs/swagger/openapi.yaml index daf9095a33..c17fc27967 100644 --- a/specs/swagger/openapi.yaml +++ b/specs/swagger/openapi.yaml @@ -59,6 +59,8 @@ tags: x-displayName: Workflow Management - name: Devtron Server version x-displayName: Devtron Server version + - name: GitOps Validation + x-displayName: GitOps Validation paths: /app/labels/list: get: @@ -2583,6 +2585,136 @@ paths: - EA_ONLY tags: - Devtron Server version + /validate: + post: + description: Validate gitops configuration by dry run + summary: Validate gitops configuration by dry run + security: + - ApiKeyAuth: [] + operationId: GitOpsValidateDryRun + requestBody: + description: A JSON object containing the gitops configuration + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/GitOpsConfigDto' + responses: + '200': + description: Successfully return all validation stages results + content: + application/json: + schema: + $ref: '#/components/schemas/DetailedError' + '400': + description: Bad Request. Input Validation error/wrong request body. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: Unauthorized User + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + tags: + - GitOps Validation + /config: + post: + description: create/save new configuration and validate them before saving + summary: create/save new configuration and validate them before saving + security: + - ApiKeyAuth: [] + operationId: CreateGitOpsConfig + requestBody: + description: A JSON object containing the gitops configuration + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/GitOpsConfigDto' + responses: + '200': + description: >- + Successfully return all validation stages results and if validation + is correct then saves the configuration in the backend + content: + application/json: + schema: + $ref: '#/components/schemas/DetailedError' + '400': + description: Bad Request. Input Validation error/wrong request body. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: Unauthorized User + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + tags: + - GitOps Validation + put: + description: >- + update configuration and validate them before saving(if last validation + is within 30 seconds then do not validate) + summary: >- + update configuration and validate them before saving(if last validation + is within 30 seconds then do not validate) + operationId: UpdateGitOpsConfig + security: + - ApiKeyAuth: [] + requestBody: + description: A JSON object containing the gitops configuration + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/GitOpsConfigDto' + responses: + '200': + description: >- + Successfully return all validation stages results and if validation + is correct then updates the configuration in the backend + content: + application/json: + schema: + $ref: '#/components/schemas/DetailedError' + '400': + description: Bad Request. Input Validation error/wrong request body. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: Unauthorized User + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + tags: + - GitOps Validation components: schemas: BulkUpdateSeeExampleResponse: @@ -4051,6 +4183,50 @@ components: isLast: type: boolean description: Indicates if this is the last node in its branch of the tree. + GitOpsConfigDto: + type: object + properties: + id: + type: integer + provider: + type: string + username: + type: string + token: + type: string + gitLabGroupId: + type: string + gitHubOrgId: + type: string + host: + type: string + active: + type: boolean + azureProjectName: + type: string + userId: + type: integer + DetailedError: + type: object + properties: + successfulStages: + type: array + items: + type: string + description: All successful stages + validatedOn: + type: string + description: Timestamp of validation + stageErrorMap: + type: array + items: + type: object + properties: + stage: + type: string + error: + type: string + description: map of stage and their respective errors requestBodies: SSOLoginDto: description: SSO Login Configuration object @@ -4242,6 +4418,10 @@ components: in: header name: X-API-Key description: API key authentication + ApiKeyAuth: + type: apiKey + in: header + name: Authorization x-tagGroups: - name: Common Devtron automation APIs tags: @@ -4263,3 +4443,4 @@ x-tagGroups: - K8s Resource - Workflow Management - Devtron Server version + - GitOps Validation \ No newline at end of file From 427da2b1bfa481027169ead3b6a4f3a8936f6ba4 Mon Sep 17 00:00:00 2001 From: kamal-devtron Date: Wed, 23 Jul 2025 16:47:57 +0530 Subject: [PATCH 4/4] added api spec for api token --- specs/apiToken_api-spec.yaml | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/specs/apiToken_api-spec.yaml b/specs/apiToken_api-spec.yaml index 76c2bcf537..ae2eafc3a8 100644 --- a/specs/apiToken_api-spec.yaml +++ b/specs/apiToken_api-spec.yaml @@ -2,10 +2,15 @@ openapi: "3.0.3" info: version: 1.0.0 title: Devtron Labs +servers: + - url: http://localhost/orchestrator paths: - /orchestrator/api-token: + /api-token: get: description: Get All active Api Tokens + summary: Get All active Api Tokens + security: + - ApiKeyAuth: [] responses: "200": description: Successfully fetched active API tokens links @@ -17,6 +22,9 @@ paths: $ref: "#/components/schemas/ApiToken" post: description: Create api-token + summary: Create Api Token + security: + - ApiKeyAuth: [] requestBody: required: true content: @@ -32,9 +40,12 @@ paths: application/json: schema: $ref: "#/components/schemas/CreateApiTokenResponse" - /orchestrator/api-token/{id}: + /api-token/{id}: put: description: Update api-token + summary: Update Api Token + security: + - ApiKeyAuth: [] parameters: - name: id in: path @@ -58,6 +69,9 @@ paths: $ref: "#/components/schemas/UpdateApiTokenResponse" delete: description: Delete api-token + summary: Delete the Api Token + security: + - ApiKeyAuth: [] parameters: - name: id in: path @@ -74,6 +88,11 @@ paths: schema: $ref: "#/components/schemas/ActionResponse" components: + securitySchemes: + ApiKeyAuth: + type: apiKey + in: header + name: Authorization schemas: ApiToken: type: object