Zededa KubernetesSecrets API

openapi: 3.2.0
info:
  title: ZEDEDA App Profiles Service AppProfileService Kubernetes Secrets API
  description: The ZEDEDA App Profiles Service is part of ZEDEDA Edge Orchestration Platform. This service enables customers to define their app profiles on ZEDEDA platform and to manage them remotely.
  termsOfService: https://www.zededa.com/terms
  version: '1.0'
  contact:
    name: ZEDEDA API Support
    url: https://www.zededa.com/support
    email: support@zededa.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: /api
security:
- BearerToken: []
tags:
- name: KubernetesSecrets
  description: APIs for managing Kubernetes secrets including SSH keys, basic authentication credentials, and other sensitive data. Supports create, read, and list operations.
paths:
  /v1/cluster/instances/kubernetes/secrets:
    get:
      summary: List all Kubernetes secrets
      description: "Retrieve a list of all configured Kubernetes secrets with their metadata and status information. Secret data is not included in list responses for security reasons.\n\n**Query Parameters:**\n- `projectId` (optional): Filter secrets by project ID\n\n**Example Request:**\n```\nGET /v1/cluster/instances/kubernetes/secrets\nGET /v1/cluster/instances/kubernetes/secrets?projectId=project-123\n```\n\n**Example Response:**\n```json\n{\n  \"secrets\": [\n    {\n      \"id\": \"secret-abc123\",\n      \"_type\": \"Secret\",\n      \"kind\": \"Secret\",\n      \"metadata\": {\n        \"name\": \"git-ssh-key\",\n        \"type\": \"SECRET_TYPE_SSH\",\n        \"creation_timestamp\": \"2024-01-15T10:30:00Z\",\n        \"project_id\": \"project-123\",\n        \"state\": {\n          \"error\": false,\n          \"message\": \"Secret is active\",\n          \"name\": \"git-ssh-key\",\n          \"transitioning\": false\n        }\n      }\n    },\n    {\n      \"id\": \"secret-def456\",\n      \"_type\": \"Secret\",\n      \"kind\": \"Secret\",\n      \"metadata\": {\n        \"name\": \"registry-credentials\",\n        \"type\": \"SECRET_TYPE_BASIC_AUTH\",\n        \"creation_timestamp\": \"2024-01-15T11:00:00Z\",\n        \"project_id\": \"project-123\",\n        \"state\": {\n          \"error\": false,\n          \"message\": \"Secret is active\",\n          \"name\": \"registry-credentials\",\n          \"transitioning\": false\n        }\n      }\n    }\n  ],\n  \"total_count\": 2\n}\n```"
      operationId: KubernetesSecrets_ListSecrets
      responses:
        '200':
          description: Successfully retrieved secrets list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretListResponse'
        '400':
          description: Bad Request. The API gateway did not process the request because of invalid value of filter parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '403':
          description: Forbidden. User does not have permission to list secrets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '500':
          description: Internal Server Error. Failed to retrieve secrets list due to server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      tags:
      - KubernetesSecrets
      parameters:
      - name: X-Request-Id
        in: header
        required: false
        description: User-Agent specified id to track a request
        schema:
          type: string
    post:
      summary: Create a new Kubernetes secret
      description: "Create a new Kubernetes secret for storing sensitive data like SSH keys, basic authentication credentials, or other secrets needed for deployments.\n\n**Example Request (SSH Secret):**\n```json\n{\n  \"metadata\": {\n    \"name\": \"git-ssh-key\",\n    \"type\": \"SECRET_TYPE_SSH\",\n    \"project_id\": \"project-123\"\n  },\n  \"data\": {\n    \"ssh_private_key\": \"-----BEGIN RSA PRIVATE KEY-----\\nMIIEpAIBAAKCAQEA...\",\n    \"ssh_public_key\": \"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ...\"\n  }\n}\n```\n\n**Example Request (SECRET_TYPE_BASIC_AUTH Secret):**\n```json\n{\n  \"metadata\": {\n    \"name\": \"registry-credentials\",\n    \"type\": \"SECRET_TYPE_BASIC_AUTH\",\n    \"project_id\": \"project-123\"\n  },\n  \"data\": {\n    \"encoded_username\": \"dXNlcm5hbWU=\",\n    \"encoded_password\": \"cGFzc3dvcmQ=\"\n  }\n}\n```\n\n**Example Response:**\n```json\n{\n  \"operationType\": \"OPS_TYPE_UNSPECIFIED\",\n  \"operationStatus\": \"OPS_STATUS_UNSPECIFIED\",\n  \"objectKind\": \"\",\n  \"objectId\": \"secret-abc123\",\n  \"objectName\": \"git-ssh-key\",\n  \"objectRevision\": \"\",\n  \"objectType\": \"OBJECT_TYPE_UNSPECIFIED\",\n  \"operationTime\": \"\",\n  \"startTime\": \"\",\n  \"endTime\": \"\",\n  \"user\": \"\",\n  \"httpStatusCode\": 201,\n  \"httpStatusMsg\": \"\",\n  \"jobId\": \"\",\n  \"error\": [\n    {\n      \"ec\": \"zMsgSucess\",\n      \"location\": \"\",\n      \"details\": \"\"\n    }\n  ]\n}\n```"
      operationId: KubernetesSecrets_CreateSecret
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '201':
          description: Successfully created Kubernetes secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '400':
          description: Bad Request. Invalid secret configuration or missing required fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '403':
          description: Forbidden. User does not have permission to create secrets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '409':
          description: Conflict. Secret with the same name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '500':
          description: Internal Server Error. Failed to create secret due to server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: X-Request-Id
        in: header
        required: false
        description: User-Agent specified id to track a request
        schema:
          type: string
      tags:
      - KubernetesSecrets
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretCreateRequest'
        required: true
  /v1/cluster/instances/kubernetes/secrets/id/{secretId}:
    get:
      summary: Get Kubernetes secret by ID
      description: "Retrieve detailed information about a specific Kubernetes secret including its metadata and decrypted data.\n\n**Example Request:**\n```\nGET /v1/cluster/instances/kubernetes/secrets/id/secret-abc123\n```\n\n**Example Response (SSH Secret):**\n```json\n{\n  \"id\": \"secret-abc123\",\n  \"_type\": \"Secret\",\n  \"kind\": \"Secret\",\n  \"metadata\": {\n    \"name\": \"git-ssh-key\",\n    \"type\": \"SECRET_TYPE_SSH\",\n    \"creation_timestamp\": \"2024-01-15T10:30:00Z\",\n    \"project_id\": \"project-123\",\n    \"state\": {\n      \"error\": false,\n      \"message\": \"Secret is active and ready\",\n      \"name\": \"git-ssh-key\",\n      \"transitioning\": false\n    }\n  },\n  \"data\": {\n    \"ssh_private_key\": \"-----BEGIN RSA PRIVATE KEY-----\\nMIIEpAIBAAKCAQEA...\",\n    \"ssh_public_key\": \"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ...\"\n  }\n}\n```\n\n**Example Response (SECRET_TYPE_BASIC_AUTH Secret):**\n```json\n{\n  \"id\": \"secret-def456\",\n  \"_type\": \"Secret\",\n  \"kind\": \"Secret\",\n  \"metadata\": {\n    \"name\": \"registry-credentials\",\n    \"type\": \"SECRET_TYPE_BASIC_AUTH\",\n    \"creation_timestamp\": \"2024-01-15T11:00:00Z\",\n    \"project_id\": \"project-123\",\n    \"state\": {\n      \"error\": false,\n      \"message\": \"Secret is active and ready\",\n      \"name\": \"registry-credentials\",\n      \"transitioning\": false\n    }\n  },\n  \"data\": {\n    \"username\": \"registry-user\",\n    \"password\": \"***\"\n  }\n}\n```"
      operationId: KubernetesSecrets_GetSecret
      responses:
        '200':
          description: Successfully retrieved secret information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretInfoResponse'
        '400':
          description: Bad Request. Invalid secret ID format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '401':
          description: Unauthorized. Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '403':
          description: Forbidden. User does not have permission to view this secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '404':
          description: Not Found. Secret with the specified ID does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        '500':
          description: Internal Server Error. Failed to retrieve secret due to server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZsrvResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/googlerpcStatus'
      parameters:
      - name: secretId
        description: Unique identifier of the secret. This field is required and must be a valid secret ID.
        in: path
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        required: false
        description: User-Agent specified id to track a request
        schema:
          type: string
      tags:
      - KubernetesSecrets
components:
  schemas:
    SecretInfoResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the secret
        _type:
          type: string
          description: Type of the secret
        kind:
          type: string
          description: Kubernetes resource kind
        metadata:
          $ref: '#/components/schemas/SecretMetadata'
          description: Metadata information for the secret
        data:
          $ref: '#/components/schemas/SSHCredentials'
          description: SSH key credentials
      description: Response containing comprehensive information about a Kubernetes secret
      title: Secret information response
    ZsrvErrorCode:
      type: string
      enum:
      - zMsgErrorNone
      - zMsgSucess
      - NotFound
      - AlreadyExists
      - VersionMismatch
      - RangeError
      - LargeResult
      - IncompleteData
      - InvalidData
      - FunctionUnsupported
      - NoMemory
      - SendFailure
      - Timeout
      - BadReqBody
      - BadReqParam
      - InvalidFieldFormat
      - UrlNotFound
      - ApiVersionNotSupported
      - Unauthorized
      - Forbidden
      - Conflict
      - NotModified
      - DependencyConflict
      - JsonFmtError
      - ProtoFmtError
      - CertError
      - DataBaseConnection
      - DBError
      - zMsgAccepted
      - zMsgCreated
      - PreConditionFailed
      - InternalServerError
      default: zMsgErrorNone
      description: "- zMsgErrorNone: common validation errors\n - IncompleteData: message had fields that weren't filled in\n - InvalidData: message contained the field that wasn't expected\n - FunctionUnsupported: this feature unavailable on this version of device\n - InvalidFieldFormat: message contained the field that wasn't correctly formatted\n - JsonFmtError: Marshal / Unmarshal errors\n - DataBaseConnection: generic DB error"
      title: ZedCould internal error code
    protobufAny:
      type: object
      properties:
        typeUrl:
          type: string
        value:
          type: string
          format: byte
    SecretCreateRequest:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/SecretMetadata'
          description: Metadata for the secret to be created. This field is required.
        data:
          $ref: '#/components/schemas/SecretData'
          description: Secret data including credentials or keys. This field is required.
      description: Request message for creating a new Kubernetes secret
      title: Secret creation request
      required:
      - metadata
      - data
    SSHCredentials:
      type: object
      properties:
        sshPrivateKey:
          type: string
          description: Base64 encoded SSH private key for authentication, Required if Secret type is SECRET_TYPE_SSH
        sshPublicKey:
          type: string
          description: Base64 encoded SSH public key for authentication, Required if Secret type is SECRET_TYPE_SSH
      description: SSH key pair credentials for SSH-based authentication
      title: SSH credentials
    SecretState:
      type: object
      properties:
        error:
          type: boolean
          description: Indicates if the secret is in an error state
        message:
          type: string
          description: Status message providing additional details about the secret state
        name:
          type: string
          description: Name of the secret in its current state
        transitioning:
          type: boolean
          description: Indicates if the secret is currently undergoing state transition
      description: Current operational state of a Kubernetes secret
      title: Secret state
    ZcOpsType:
      type: string
      enum:
      - OPS_TYPE_UNSPECIFIED
      - OPS_TYPE_READ
      - OPS_TYPE_DELETE
      - OPS_TYPE_CREATE
      - OPS_TYPE_UPDATE
      - OPS_TYPE_LIST
      default: OPS_TYPE_UNSPECIFIED
      title: ZedCloud internal operation type
    SecretListResponse:
      type: object
      properties:
        secrets:
          type: array
          items:
            $ref: '#/components/schemas/SecretInfoResponse'
          description: List of secrets with their detailed information
        totalCount:
          type: integer
          format: int32
          description: Total number of secrets available
      description: Response containing a list of Kubernetes secrets with pagination information
      title: Secret list response
    googlerpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
    SecretType:
      type: string
      enum:
      - SECRET_TYPE_UNSPECIFIED
      - SECRET_TYPE_SSH
      - SECRET_TYPE_BASIC_AUTH
      - SECRET_TYPE_NONE
      default: SECRET_TYPE_UNSPECIFIED
      title: Kubernetes Secret Types
    ZsrvResponse:
      type: object
      properties:
        operationType:
          $ref: '#/components/schemas/ZcOpsType'
          title: "Describes one of the operations type : possible values\n                        Read/Delete/Create/Update/List"
        operationStatus:
          $ref: '#/components/schemas/ZcOpsStatus'
          title: if this is log running job
        objectKind:
          type: string
          title: zedcloud object kind on which the operation was performed
        objectId:
          type: string
          title: Unique value identifies the object that was operated on
        objectName:
          type: string
          title: name of the object
        objectRevision:
          type: string
          title: 'object revision post the operation, note Read operation

            doesn''t change the revision'
        objectType:
          $ref: '#/components/schemas/ObjectType'
        operationTime:
          type: string
          title: time of operation
        startTime:
          type: string
          title: total time taken by operations
        endTime:
          type: string
        user:
          type: string
          title: the operation is performed on behalf of this user
        httpStatusCode:
          type: integer
          format: int32
          title: http response
        httpStatusMsg:
          type: string
          title: summary of the error in text format
        jobId:
          type: string
          title: for tracking asynchronous tasks
        error:
          type: array
          items:
            $ref: '#/components/schemas/ZsrvError'
          title: 'one or more errors will be set if the operation failed

            i.e. httpStatusCode != 2xx'
    ZsrvError:
      type: object
      properties:
        ec:
          $ref: '#/components/schemas/ZsrvErrorCode'
          title: 'Enumrated error code, describes more granular numerical

            value than just httpStatus'
        location:
          type: string
          title: 'Ignore: Internal field only'
        details:
          type: string
          title: Field captures string description of details
    ObjectType:
      type: string
      enum:
      - OBJECT_TYPE_UNSPECIFIED
      - OBJECT_TYPE_USER
      - OBJECT_TYPE_EDGE_NODE
      - OBJECT_TYPE_EDGE_APP
      - OBJECT_TYPE_IMAGE
      - OBJECT_TYPE_EDGE_APP_INSTANCE
      - OBJECT_TYPE_PROJECT
      - OBJECT_TYPE_NETWORK
      - OBJECT_TYPE_DATASTORE
      - OBJECT_TYPE_SERVICE
      - OBJECT_TYPE_SERVICE_INSTANCE
      - OBJECT_TYPE_ENTERPRISE
      - OBJECT_TYPE_ROLE
      - OBJECT_TYPE_CREDENTIAL
      - OBJECT_TYPE_NETWORK_INSTANCE
      - OBJECT_TYPE_VOLUME_INSTANCE
      - OBJECT_TYPE_REALM
      - OBJECT_TYPE_AUTHPROFILE
      - OBJECT_TYPE_POLICY
      - OBJECT_TYPE_APP_POLICY
      - OBJECT_TYPE_CLUSTER_INSTANCE
      - OBJECT_TYPE_PLUGIN
      - OBJECT_TYPE_DOC_POLICY
      - OBJECT_TYPE_ORCHESTRATOR_CLUSTER
      - OBJECT_TYPE_TAGS
      - OBJECT_TYPE_EDGE_NODE_INTERFACE
      - OBJECT_TYPE_DEPLOYMENT
      - OBJECT_TYPE_ENTITLEMENTS
      - OBJECT_TYPE_DATA_STREAM
      - OBJECT_TYPE_API_USAGE
      - OBJECT_TYPE_APP_INSTANCE_SNAPSHOT
      - OBJECT_TYPE_PATCH_ENVELOPE
      - OBJECT_TYPE_RESOURCE_USAGE_TRACK
      - OBJECT_TYPE_PATCH_ENVELOPE_REFERENCE
      - OBJECT_TYPE_DEV_PASSTHROUGH
      - OBJECT_TYPE_EDGE_NODE_CLUSTER
      - OBJECT_TYPE_ASSET_GROUP
      - OBJECT_TYPE_APP_PROFILE
      - OBJECT_TYPE_PROFILE_DEPLOYMENT
      - OBJECT_TYPE_ZKS_INSTANCE
      - OBJECT_TYPE_CLUSTER_GROUP
      default: OBJECT_TYPE_UNSPECIFIED
    SecretMetadata:
      type: object
      properties:
        name:
          type: string
          description: Name of the Kubernetes secret. This field is required and must be a valid Kubernetes secret name.
          maxLength: 253
          minLength: 1
          pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
        type:
          $ref: '#/components/schemas/SecretType'
          description: Type of the secret (SECRET_TYPE_SSH, SECRET_TYPE_BASIC_AUTH, SECRET_TYPE_UNSPECIFIED, SECRET_TYPE_NONE). This field is required and must be a valid Kubernetes secret type.
        creationTimestamp:
          type: string
          description: Timestamp when the secret was created
        projectId:
          type: string
          description: Project identifier that owns this secret
        state:
          $ref: '#/components/schemas/SecretState'
          description: Current state of the secret including error status and transition information
      description: Metadata information for a Kubernetes secret including name, type, and state
      title: Kubernetes secret metadata
      required:
      - name
      - type
    SecretData:
      type: object
      properties:
        encodedUsername:
          type: string
          description: Base64 encoded username for basic authentication, Required if Secret type is SECRET_TYPE_BASIC_AUTH
        encodedPassword:
          type: string
          description: Base64 encoded password for basic authentication, Required if Secret type is SECRET_TYPE_BASIC_AUTH
        sshPublicKey:
          type: string
          description: Base64 encoded SSH public key for SSH authentication, Required if Secret type is SECRET_TYPE_SSH
        sshPrivateKey:
          type: string
          description: Base64 encoded SSH private key for SSH authentication, Required if Secret type is SECRET_TYPE_SSH
      description: Raw data for Kubernetes secrets including encoded credentials and SSH keys
      title: Kubernetes secret data
    ZcOpsStatus:
      type: string
      enum:
      - OPS_STATUS_UNSPECIFIED
      - OPS_STATUS_PENDING
      - OPS_STATUS_ONGOING
      - OPS_STATUS_COMPLETE
      default: OPS_STATUS_UNSPECIFIED
      description: "- OPS_STATUS_PENDING: In rare cases, system may not start operation when it was requested. Client will be notified that operation is PENDING\n - OPS_STATUS_ONGOING: system will start the operation, but at the time response was generated, operation is still ONGOING.\n - OPS_STATUS_COMPLETE: Even if the result of the operations may result in failure, but the OpsStatus will marked COMPLETE for almost all cases."
      title: ZedCloud internal operation status
  securitySchemes:
    BearerToken:
      type: apiKey
      description: Bearer token for user session
      name: Authorization
      in: header
externalDocs:
  description: ZEDEDA Product Documentation
  url: https://docs.zededa.com/-M-8m8d8KqdLpfOgY_jo/app-profiles