openapi: 3.1.0 info: title: Kuma Dataplane MeshIdentity API description: Kuma API version: v1alpha1 x-ref-schema-name: DataplaneOverview security: - BasicAuth: [] - BearerAuth: [] - {} tags: - name: MeshIdentity paths: /meshes/{mesh}/meshidentities/{name}: get: operationId: getMeshIdentity summary: Returns MeshIdentity entity tags: - MeshIdentity parameters: - in: path name: mesh schema: type: string required: true description: name of the mesh - in: path name: name schema: type: string required: true description: name of the MeshIdentity responses: '200': $ref: '#/components/responses/MeshIdentityItem' '404': $ref: '#/components/responses/NotFound' put: operationId: putMeshIdentity summary: Creates or Updates MeshIdentity entity tags: - MeshIdentity parameters: - in: path name: mesh schema: type: string required: true description: name of the mesh - in: path name: name schema: type: string required: true description: name of the MeshIdentity requestBody: description: Put request required: true content: application/json: schema: $ref: '#/components/schemas/MeshIdentityItem' responses: '200': $ref: '#/components/responses/MeshIdentityCreateOrUpdateSuccessResponse' '201': $ref: '#/components/responses/MeshIdentityCreateOrUpdateSuccessResponse' delete: operationId: deleteMeshIdentity summary: Deletes MeshIdentity entity tags: - MeshIdentity parameters: - in: path name: mesh schema: type: string required: true description: name of the mesh - in: path name: name schema: type: string required: true description: name of the MeshIdentity responses: '200': $ref: '#/components/responses/MeshIdentityDeleteSuccessResponse' '404': $ref: '#/components/responses/NotFound' /meshes/{mesh}/meshidentities: get: operationId: getMeshIdentityList summary: Returns a list of MeshIdentity in the mesh. tags: - MeshIdentity parameters: - in: query name: offset description: offset in the list of entities required: false schema: type: integer example: 0 - in: query name: size description: the number of items per page required: false schema: type: integer default: 100 maximum: 1000 minimum: 1 - in: query name: filter description: filter by labels when multiple filters are present, they are ANDed required: false schema: type: object properties: key: type: string value: type: string example: label.k8s.kuma.io/namespace: my-ns - in: path name: mesh schema: type: string required: true description: name of the mesh responses: '200': $ref: '#/components/responses/MeshIdentityList' components: responses: NotFound: description: Not Found content: application/problem+json: schema: $ref: '#/components/schemas/NotFoundError' MeshIdentityCreateOrUpdateSuccessResponse: description: Successful response content: application/json: schema: type: object properties: warnings: type: array readOnly: true description: 'warnings is a list of warning messages to return to the requesting Kuma API clients. Warning messages describe a problem the client making the API request should correct or be aware of. ' items: type: string MeshIdentityItem: description: Successful response content: application/json: schema: $ref: '#/components/schemas/MeshIdentityItem' MeshIdentityList: description: List content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/MeshIdentityItem' total: type: number description: The total number of entities next: type: string description: URL to the next page MeshIdentityDeleteSuccessResponse: description: Successful response content: application/json: schema: type: object schemas: NotFoundError: allOf: - $ref: '#/components/schemas/Error' - type: object properties: status: type: integer enum: - 404 example: 404 description: 'The HTTP status code for NotFoundError MUST be 404. ' title: type: string example: Not Found type: type: string example: https://httpstatuses.com/404 detail: type: string example: The requested resource was not found MeshIdentityItem: type: object description: MeshIdentity manages service identity and certificate provisioning for workloads in the mesh. It configures how services obtain their identity certificates, supporting multiple providers including bundled certificates (self-signed or user-provided CA), SPIRE integration, and custom SPIFFE ID configuration for secure service-to-service authentication. required: - type - name - spec properties: type: description: the type of the resource type: string enum: - MeshIdentity mesh: description: Mesh is the name of the Kuma mesh this resource belongs to. It may be omitted for cluster-scoped resources. type: string default: default kri: description: A unique identifier for this resource instance used by internal tooling and integrations. Typically derived from resource attributes and may be used for cross-references or indexing type: string readOnly: true example: kri_mid_default_zone-east_kuma-system_myresource1_ name: description: Name of the Kuma resource type: string labels: additionalProperties: type: string description: The labels to help identity resources type: object spec: description: Spec is the specification of the Kuma MeshIdentity resource. properties: provider: properties: bundled: description: 'Bundled provides information about certificates that are generated by the control plane, either autogenerated or provided by the user.' properties: autogenerate: description: Autogenerate configures the control plane to use self-signed certificates. properties: enabled: type: boolean type: object ca: description: CA has configuration related to the CA properties: certificate: description: Certificate allows the user to specify a custom certificate. properties: envVar: properties: name: type: string required: - name type: object file: properties: path: type: string required: - path type: object insecureInline: properties: value: type: string required: - value type: object secretRef: properties: kind: enum: - Secret type: string name: type: string required: - kind - name type: object type: enum: - File - Secret - EnvVar - InsecureInline type: string required: - type type: object privateKey: description: PrivateKey allows the user to specify a custom private key. properties: envVar: properties: name: type: string required: - name type: object file: properties: path: type: string required: - path type: object insecureInline: properties: value: type: string required: - value type: object secretRef: properties: kind: enum: - Secret type: string name: type: string required: - kind - name type: object type: enum: - File - Secret - EnvVar - InsecureInline type: string required: - type type: object type: object certificateParameters: description: CertificateParameters allows users to define certificate generation parameters. properties: expiry: type: string type: object insecureAllowSelfSigned: description: InsecureAllowSelfSigned allows users to enable the use of self-signed certificates. type: boolean meshTrustCreation: description: 'MeshTrustCreation defines whether a MeshTrust resource should be automatically created from an existing MeshIdentity. If not defined, the control plane automatically generates a MeshTrust.' enum: - Enabled - Disabled type: string type: object extension: description: Extension indicates that custom provider is used. properties: config: description: Config is a freeform configuration for the extension. x-kubernetes-preserve-unknown-fields: true name: description: Name is the name of the extension provider. type: string required: - name type: object spire: description: Spire indicates that SPIRE is used for certificate delivery. properties: agent: description: Spire agent configuration properties: timeout: description: 'Connection timeout to the socket exposed by Spire agent Default 1 second.' type: string type: object type: object type: description: Type specifies the type of certificate provider. enum: - Bundled - Spire - Extension type: string required: - type type: object selector: properties: dataplane: properties: matchLabels: additionalProperties: type: string type: object type: object type: object spiffeID: properties: path: type: string trustDomain: type: string type: object type: object creationTime: readOnly: true type: string description: Time at which the resource was created format: date-time example: '0001-01-01T00:00:00Z' modificationTime: readOnly: true type: string description: Time at which the resource was updated format: date-time example: '0001-01-01T00:00:00Z' status: description: Status is the current status of the Kuma MeshIdentity resource. properties: conditions: description: Conditions is an array of hostname generator conditions. items: properties: message: description: 'message is a human readable message indicating details about the transition. This may be an empty string.' maxLength: 32768 type: string reason: description: 'reason contains a programmatic identifier indicating the reason for the condition''s last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.' maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ type: string status: description: status of the condition, one of True, False, Unknown. enum: - 'True' - 'False' - Unknown type: string type: description: type of condition in CamelCase or in foo.example.com/CamelCase. maxLength: 316 pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string required: - message - reason - status - type type: object type: array x-kubernetes-list-map-keys: - type x-kubernetes-list-type: map type: object readOnly: true InvalidParameters: type: object title: Invalid Parameters required: - field - reason - source properties: field: type: string description: The name of the field that caused the error. reason: type: string description: 'A short, human-readable description of the problem. _Should_ be provided as "Sentence case" for direct use in a UI. ' rule: type: string description: 'May be provided as a hint to the user to help understand the type of failure. Additional guidance may be provided in additional fields, i.e. `choices`. ' choices: type: array description: 'Optional field to provide a list of valid choices for the field that caused the error. ' items: type: string source: type: string description: 'The location of the field that caused the error. ' enum: - body - query - header - path Error: type: object title: Error description: 'Standard error. Follows the [AIP #193 - Errors](https://kong-aip.netlify.app/aip/193/) specification. ' x-examples: Example 1: status: 404 title: Not Found type: https://kongapi.info/konnect/not-found instance: portal:trace:2287285207635123011 detail: The requested document was not found required: - status - title - instance - type - detail properties: status: type: integer description: The HTTP status code. example: 404 title: type: string description: 'A short, human-readable summary of the problem. It **should not** change between occurrences of a problem, except for localization. Should be provided as "Sentence case" for potential direct use in a UI ' example: Not Found type: type: string description: 'A unique identifier for this error. When dereferenced it must provide human-readable documentation for the problem. ' example: Not Found instance: type: string example: portal:trace:2287285207635123011 description: 'Used to return the correlation ID back to the user, in the format `:trace:`. ' detail: type: string example: The requested team was not found description: 'A human readable explanation specific to this occurrence of the problem. This field may contain request/entity data to help the user understand what went wrong. Enclose variable values in square brackets. _Should_ be provided as "Sentence case" for direct use in a UI ' invalid_parameters: type: array description: 'All 400 errors **MUST** return an `invalid_parameters` key in the response. Used to indicate which fields have invalid values when validated. ' items: $ref: '#/components/schemas/InvalidParameters' securitySchemes: BasicAuth: type: http scheme: basic BearerAuth: type: http scheme: bearer