From a3385a23cc3e3786ae903663475ab95f89ef12c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antonio=20G=C3=A1mez=2C=20PhD?= Date: Fri, 4 Nov 2022 17:13:12 +0100 Subject: [PATCH] Regenerate `openapi.yaml` file (#5610) ### Description of the change This PR updates the public `openapi.yaml` file we are bundling along with the dashboard component. We forgot to do it (we were deprecating components like kubeops and assetsvc and we just missed it). As reported, there were some mismatches in our API docs, so a sync was required by all means. Additionally, I've squeezed a few words in the release process docs not to forget about it in the next releases. ### Benefits Public OpenAPI file will get in sync again. ### Possible drawbacks N/A (we will have to repeat the process once #5591 gets merged) ### Applicable issues - fixes #5609 ### Additional information ![image](https://user-images.githubusercontent.com/11535726/199968880-336492bd-828b-461a-b0e3-c1e0b90529b0.png) Signed-off-by: Antonio Gamez Diaz --- dashboard/public/openapi.yaml | 1289 +++++++++-------- .../reference/developer/release-process.md | 9 +- 2 files changed, 655 insertions(+), 643 deletions(-) diff --git a/dashboard/public/openapi.yaml b/dashboard/public/openapi.yaml index 8dc17cef656..5489a6c28a6 100644 --- a/dashboard/public/openapi.yaml +++ b/dashboard/public/openapi.yaml @@ -839,8 +839,14 @@ paths: properties: context: type: object - description: The context (cluster/namespace) for the package. - title: Installed package context + description: |- + Installed package context + + The context (cluster/namespace) for the package. + title: |- + Installed package context + + The context (cluster/namespace) for the package. plugin: type: object example: @@ -879,8 +885,10 @@ paths: reconciliationOptions: $ref: "#/components/schemas/v1alpha1ReconciliationOptions" description: >- - Request for UpdateInstalledPackage. The intent is to reach the - desired state specified + UpdateInstalledPackageRequest + + + Request for UpdateInstalledPackage. The intent is to reach the desired state specified by the fields in the request, while leaving other fields intact. This is a whole @@ -899,7 +907,6 @@ paths: So the meaning of each field value is describing the desired state of the corresponding field in the resource after the update operation has completed the renconciliation. - title: UpdateInstalledPackageRequest required: true tags: - PackagesService @@ -1365,11 +1372,10 @@ paths: type: string description: A user-provided description. interval: - type: integer - format: int64 + type: string title: >- The interval at which to check the upstream for updates (in - seconds) + time+unit) Optional. Defaults to 10m if not specified tlsConfig: @@ -1378,8 +1384,10 @@ paths: $ref: "#/components/schemas/v1alpha1PackageRepositoryAuth" customDetail: $ref: "#/components/schemas/protobufAny" - description: Request for UpdatePackageRepository - title: UpdatePackageRepositoryRequest + title: |- + UpdatePackageRepositoryRequest + + Request for UpdatePackageRepository required: true tags: - RepositoriesService @@ -3453,17 +3461,31 @@ paths: properties: context: type: object - description: The context (cluster/namespace) for the package. - title: Installed package context + description: |- + Installed package context + + The context (cluster/namespace) for the package. + title: |- + Installed package context + + The context (cluster/namespace) for the package. plugin: $ref: "#/components/schemas/v1alpha1Plugin" - description: A reference uniquely identifying the installed package. - title: Installed package reference + description: |- + Installed package reference + + A reference uniquely identifying the installed package. + title: |- + Installed package reference + + A reference uniquely identifying the installed package. releaseRevision: type: integer format: int32 - description: A number identifying the Helm revision to which to rollback. - title: ReleaseRevision + description: |- + ReleaseRevision + + A number identifying the Helm revision to which to rollback. required: true tags: - HelmPackagesService @@ -4973,6 +4995,89 @@ paths: type: string tags: - ResourcesService + "/apis/plugins/resources/v1alpha1/c/{context.cluster}/can-i": + post: + operationId: ResourcesService_CanI + responses: + "200": + description: A successful response. + content: + application/json: + schema: + $ref: "#/components/schemas/v1alpha1CanIResponse" + "401": + description: Returned when the user does not have permission to access the + resource. + content: + application/json: + schema: {} + default: + description: An unexpected error response. + content: + application/json: + schema: + $ref: "#/components/schemas/rpcStatus" + parameters: + - name: context.cluster + description: >- + Cluster + + + A cluster name can be provided to target a specific cluster if multiple + + clusters are configured, otherwise all clusters will be assumed. + in: path + required: true + schema: + type: string + - name: context.namespace + description: >- + Namespace + + + A namespace must be provided if the context of the operation is for a resource + + or resources in a particular namespace. + + For requests to list items, not including a namespace here implies that the context + + for the request is everything the requesting user can read, though the result can + + be filtered by any filtering options of the request. Plugins may choose to return + + Unimplemented for some queries for which we do not yet have a need. + in: query + required: false + schema: + type: string + - name: group + description: |- + Group API Group of the Resource. "*" means all. + +optional + in: query + required: false + schema: + type: string + - name: resource + description: |- + Resource is one of the existing resource types. "*" means all. + +optional + in: query + required: false + schema: + type: string + - name: verb + description: >- + Verb is a kubernetes resource API verb, like: get, list, watch, + create, update, delete, proxy. "*" means all. + + +optional + in: query + required: false + schema: + type: string + tags: + - ResourcesService "/apis/plugins/resources/v1alpha1/c/{context.cluster}/ns": post: operationId: ResourcesService_CreateNamespace @@ -5395,49 +5500,6 @@ components: scheme: bearer bearerFormat: JWT requestBodies: - FluxV2RepositoriesService_UpdatePackageRepositoryBody: - content: - application/json: - schema: - type: object - properties: - packageRepoRef: - type: object - properties: - context: - type: object - description: The context (cluster/namespace) for the repository. - title: The context (cluster/namespace) for the repository. - plugin: - $ref: "#/components/schemas/v1alpha1Plugin" - title: >- - A reference uniquely identifying the package repository being - updated. - - The only required field - url: - type: string - description: URL identifying the package repository location. - description: - type: string - description: A user-provided description. - interval: - type: integer - format: int64 - title: >- - The interval at which to check the upstream for updates (in - seconds) - - Optional. Defaults to 10m if not specified - tlsConfig: - $ref: "#/components/schemas/v1alpha1PackageRepositoryTlsConfig" - auth: - $ref: "#/components/schemas/v1alpha1PackageRepositoryAuth" - customDetail: - $ref: "#/components/schemas/protobufAny" - description: Request for UpdatePackageRepository - title: UpdatePackageRepositoryRequest - required: true v1alpha1AddPackageRepositoryRequest: content: application/json: @@ -5461,8 +5523,14 @@ components: properties: context: type: object - description: The context (cluster/namespace) for the package. - title: Installed package context + description: |- + Installed package context + + The context (cluster/namespace) for the package. + title: |- + Installed package context + + The context (cluster/namespace) for the package. plugin: $ref: "#/components/schemas/v1alpha1Plugin" title: >- @@ -5488,8 +5556,10 @@ components: reconciliationOptions: $ref: "#/components/schemas/v1alpha1ReconciliationOptions" description: >- - Request for UpdateInstalledPackage. The intent is to reach the - desired state specified + UpdateInstalledPackageRequest + + + Request for UpdateInstalledPackage. The intent is to reach the desired state specified by the fields in the request, while leaving other fields intact. This is a whole @@ -5508,336 +5578,79 @@ components: So the meaning of each field value is describing the desired state of the corresponding field in the resource after the update operation has completed the renconciliation. - title: UpdateInstalledPackageRequest required: true + FluxV2RepositoriesService_UpdatePackageRepositoryBody: + content: + application/json: + schema: + type: object + properties: + packageRepoRef: + type: object + properties: + context: + type: object + description: The context (cluster/namespace) for the repository. + title: The context (cluster/namespace) for the repository. + plugin: + $ref: "#/components/schemas/v1alpha1Plugin" + title: >- + A reference uniquely identifying the package repository being + updated. + + The only required field + url: + type: string + description: URL identifying the package repository location. + description: + type: string + description: A user-provided description. + interval: + type: string + title: >- + The interval at which to check the upstream for updates (in + time+unit) + + Optional. Defaults to 10m if not specified + tlsConfig: + $ref: "#/components/schemas/v1alpha1PackageRepositoryTlsConfig" + auth: + $ref: "#/components/schemas/v1alpha1PackageRepositoryAuth" + customDetail: + $ref: "#/components/schemas/protobufAny" + title: |- + UpdatePackageRepositoryRequest + + Request for UpdatePackageRepository + required: true + schemas: - # pkg/chart/chart.go - Details: - type: object - additionalProperties: false - properties: - appRepositoryResourceName: - type: string - appRepositoryResourceNamespace: - type: string - chartName: - type: string - releaseName: - type: string - version: - type: string - values: - type: string - # pkg/proxy/proxy.go - AppOverview: - type: object - additionalProperties: false - properties: - releaseName: - type: string - version: - type: string - namespace: - type: string - icon: - type: string - status: - type: string - chart: - type: string - chartMetadata: - $ref: "#/components/schemas/ChartMetadata" - # pkg/kube/kube_handler.go - AppRepositoryRequestDetails: + PackageRepositoryAuthPackageRepositoryAuthType: + type: string + enum: + - PACKAGE_REPOSITORY_AUTH_TYPE_UNSPECIFIED + - PACKAGE_REPOSITORY_AUTH_TYPE_BASIC_AUTH + - PACKAGE_REPOSITORY_AUTH_TYPE_TLS + - PACKAGE_REPOSITORY_AUTH_TYPE_BEARER + - PACKAGE_REPOSITORY_AUTH_TYPE_AUTHORIZATION_HEADER + - PACKAGE_REPOSITORY_AUTH_TYPE_DOCKER_CONFIG_JSON + - PACKAGE_REPOSITORY_AUTH_TYPE_SSH + - PACKAGE_REPOSITORY_AUTH_TYPE_OPAQUE + default: PACKAGE_REPOSITORY_AUTH_TYPE_UNSPECIFIED + pluginsfluxv2packagesv1alpha1SetUserManagedSecretsResponse: type: object - additionalProperties: false properties: - name: - type: string - type: - type: string - description: - type: string - repoURL: - type: string - authHeader: - type: string - customCA: - type: string - registrySecrets: - type: array - items: - type: string - syncJobPodTemplate: - $ref: "#/components/schemas/PodTemplateSpec" - resyncRequests: - type: integer - format: int64 - ociRepositories: - type: array - items: - type: string - tlsInsecureSkipVerify: - type: boolean - passCredentials: + value: type: boolean - # pkg/kube/kube_handler.go - ValidationResponse: - type: object - additionalProperties: false - properties: - code: - type: integer - format: int64 - message: - type: string - # pkg/http-handler/http-handler.go - AllowedResponse: - type: object - additionalProperties: false - properties: - allowed: - type: string - # pkg/http-handler/http-handler.go - AppRepositoryResponse: - type: object - additionalProperties: false - properties: - appRepository: - $ref: "#/components/schemas/AppRepositoryList" - # pkg/http-handler/http-handler.go - AppRepositoryRequest: - type: object - additionalProperties: false - properties: - appRepository: - $ref: "#/components/schemas/AppRepositoryRequestDetails" - # cmd/apprepository-controller/pkg/apis/apprepository/v1alpha1/types.go - AppRepositoryList: - type: object - additionalProperties: false - properties: - metadata: - type: object - items: - type: array - items: - $ref: "#/components/schemas/AppRepository" - # cmd/apprepository-controller/pkg/apis/apprepository/v1alpha1/types.go - AppRepository: + pluginshelmpackagesv1alpha1SetUserManagedSecretsResponse: type: object - additionalProperties: false properties: - metadata: - type: object - spec: - $ref: "#/components/schemas/AppRepositorySpec" - status: - $ref: "#/components/schemas/AppRepositoryStatus" - # cmd/apprepository-controller/pkg/apis/apprepository/v1alpha1/types.go - AppRepositorySpec: + value: + type: boolean + protobufAny: type: object - additionalProperties: false properties: - type: - type: string - url: - type: string - auth: - $ref: "#/components/schemas/AppRepositoryAuth" - resyncRequests: - type: integer - format: int64 - syncJobPodTemplate: - type: object - dockerRegistrySecrets: - type: array - items: - type: string - ociRepositories: - type: array - items: - type: string - tlsInsecureSkipVerify: - type: boolean - description: - type: string - passCredentials: - type: boolean - # cmd/apprepository-controller/pkg/apis/apprepository/v1alpha1/types.go - AppRepositoryStatus: - type: object - additionalProperties: false - properties: - status: - type: string - # cmd/apprepository-controller/pkg/apis/apprepository/v1alpha1/types.go - AppRepositoryAuth: - type: object - additionalProperties: false - properties: - header: - $ref: "#/components/schemas/AppRepositoryAuthHeader" - customCA: - $ref: "#/components/schemas/AppRepositoryCustomCA" - # cmd/apprepository-controller/pkg/apis/apprepository/v1alpha1/types.go - AppRepositoryAuthHeader: - type: object - additionalProperties: false - properties: - secretKeyRef: - type: object - # cmd/apprepository-controller/pkg/apis/apprepository/v1alpha1/types.go - AppRepositoryCustomCA: - type: object - additionalProperties: false - properties: - secretKeyRef: - type: object - # pkg/mod/k8s.io/api/core/v1/types.go - PodTemplateSpec: - type: object - additionalProperties: false - properties: - metadata: - type: object - spec: - type: object - # pkg/mod/k8s.io/api/core/v1/types.go - Namespace: - type: object - properties: - metadata: - type: object - spec: - type: object - status: - type: object - # pkg/mod/k8s.io/api/authorization/v1/types.go - ResourceAttributes: - type: object - additionalProperties: false - properties: - namespace: - type: string - verb: - type: string - group: - type: string - version: - type: string - resource: - type: string - subresource: - type: string - name: - type: string - # pkg/mod/k8s.io/helm@v2.16.0+incompatible/pkg/proto/hapi/chart/metadata.pb.go - ChartMetadata: - type: object - additionalProperties: false - properties: - annotations: - type: object - apiVersion: - type: string - appVersion: - type: string - condition: - type: string - deprecated: - type: boolean - description: - type: string - engine: - type: string - home: - type: string - icon: - type: string - kubeVersion: - type: string - maintainers: - type: array - items: - type: object - properties: - name: - type: string - email: - type: string - url: - type: string - name: - type: string - sources: - type: array - items: - type: string - tags: - type: string - version: - type: string - # pkg/mod/helm.sh/helm/v3@v3.5.0/pkg/release/release.go - Release: - type: object - additionalProperties: false - properties: - name: - type: string - info: - type: string - chart: - type: object - config: - type: string - manifest: - type: string - hooks: - type: array - items: - type: object - version: - type: integer - format: int64 - namespace: - type: string - Error: - type: object - additionalProperties: false - properties: - code: - type: integer - format: int64 - message: - type: string - # Temporarily manually extracted from /cmd/kubeapps-apis/docs/kubeapps-apis.swagger.json - PackageRepositoryAuthPackageRepositoryAuthType: - type: string - enum: - - PACKAGE_REPOSITORY_AUTH_TYPE_UNSPECIFIED - - PACKAGE_REPOSITORY_AUTH_TYPE_BASIC_AUTH - - PACKAGE_REPOSITORY_AUTH_TYPE_TLS - - PACKAGE_REPOSITORY_AUTH_TYPE_BEARER - - PACKAGE_REPOSITORY_AUTH_TYPE_AUTHORIZATION_HEADER - - PACKAGE_REPOSITORY_AUTH_TYPE_DOCKER_CONFIG_JSON - - PACKAGE_REPOSITORY_AUTH_TYPE_SSH - - PACKAGE_REPOSITORY_AUTH_TYPE_OPAQUE - default: PACKAGE_REPOSITORY_AUTH_TYPE_UNSPECIFIED - pluginsfluxv2packagesv1alpha1SetUserManagedSecretsResponse: - type: object - properties: - value: - type: boolean - pluginshelmpackagesv1alpha1SetUserManagedSecretsResponse: - type: object - properties: - value: - type: boolean - protobufAny: - type: object - properties: - "@type": + "@type": type: string description: >- A URL/resource name that uniquely identifies the type of the @@ -5915,7 +5728,7 @@ components: foo = any.unpack(Foo.class); } - Example 3: Pack and unpack a message in Python. + Example 3: Pack and unpack a message in Python. foo = Foo(...) any = Any() @@ -5925,18 +5738,18 @@ components: any.Unpack(foo) ... - Example 4: Pack and unpack a message in Go + Example 4: Pack and unpack a message in Go - foo := &pb.Foo{...} - any, err := anypb.New(foo) - if err != nil { - ... - } - ... - foo := &pb.Foo{} - if err := any.UnmarshalTo(foo); err != nil { - ... - } + foo := &pb.Foo{...} + any, err := anypb.New(foo) + if err != nil { + ... + } + ... + foo := &pb.Foo{} + if err := any.UnmarshalTo(foo); err != nil { + ... + } The pack methods provided by protobuf library will by default use @@ -5951,7 +5764,6 @@ components: JSON - ==== The JSON representation of an `Any` value uses the regular @@ -6018,9 +5830,9 @@ components: In general, each plug-in will define an acceptable set of valid types - - for direct helm plug-in valid values are: helm, oci + - for direct helm plug-in valid values are: "helm" and "oci" - - for flux plug-in currently only supported value is helm. In the + - for flux plug-in valid values are: "helm" and "oci". In the future, we may add support for git and/or AWS s3-style buckets url: type: string @@ -6028,10 +5840,11 @@ components: A URL identifying the package repository location. Must contain at least a protocol and host interval: - type: integer - format: int64 - title: |- - The interval at which to check the upstream for updates (in seconds) + type: string + title: >- + The interval at which to check the upstream for updates (in + time+unit) + Optional. Defaults to 10m if not specified tlsConfig: $ref: "#/components/schemas/v1alpha1PackageRepositoryTlsConfig" @@ -6041,15 +5854,19 @@ components: $ref: "#/components/schemas/v1alpha1Plugin" customDetail: $ref: "#/components/schemas/protobufAny" - description: Request for AddPackageRepository - title: AddPackageRepositoryRequest + title: |- + AddPackageRepositoryRequest + + Request for AddPackageRepository v1alpha1AddPackageRepositoryResponse: type: object properties: packageRepoRef: $ref: "#/components/schemas/v1alpha1PackageRepositoryReference" - description: Response for AddPackageRepositoryRequest - title: AddPackageRepositoryResponse + title: |- + AddPackageRepositoryResponse + + Response for AddPackageRepositoryRequest v1alpha1AvailablePackageDetail: type: object properties: @@ -6057,8 +5874,10 @@ components: $ref: "#/components/schemas/v1alpha1AvailablePackageReference" name: type: string - description: The name of the available package - title: Available package name + title: |- + Available package name + + The name of the available package version: $ref: "#/components/schemas/v1alpha1PackageAppVersion" repoUrl: @@ -6069,32 +5888,43 @@ components: title: the url of the “home” for the package iconUrl: type: string - description: A url for an icon. - title: Available package icon URL + description: |- + Available package icon URL + + A url for an icon. displayName: type: string - description: A name as displayed to users - title: Available package display name + title: |- + Available package display name + + A name as displayed to users shortDescription: type: string - description: A short description of the app provided by the package - title: Available package short description + title: |- + Available package short description + + A short description of the app provided by the package longDescription: type: string - description: A longer description of the package, a few sentences. - title: Available package long description + description: |- + Available package long description + + A longer description of the package, a few sentences. readme: type: string - description: A longer README with potentially pages of formatted Markdown. - title: Available package readme + description: |- + Available package readme + + A longer README with potentially pages of formatted Markdown. defaultValues: type: string description: >- - An example of default values used during package templating that can - serve + Available package default values + + + An example of default values used during package templating that can serve as documentation or a starting point for user customization. - title: Available package default values valuesSchema: type: string sourceUrls: @@ -6106,24 +5936,28 @@ components: type: array items: $ref: "#/components/schemas/v1alpha1Maintainer" - description: List of Maintainer - title: Available package maintainers + title: |- + Available package maintainers + + List of Maintainer categories: type: array items: type: string - description: >- - A user-facing list of category names useful for creating richer user - interfaces. + title: >- + Available package categories + + + A user-facing list of category names useful for creating richer user interfaces. Plugins can choose not to implement this - title: Available package categories customDetail: $ref: "#/components/schemas/protobufAny" description: |- + AvailablePackageDetail + An AvailablePackageDetail provides additional details required when inspecting an individual package. - title: AvailablePackageDetail v1alpha1AvailablePackageReference: type: object properties: @@ -6132,6 +5966,9 @@ components: identifier: type: string description: >- + Available package identifier + + The fully qualified identifier for the available package (ie. a unique name for the context). For some packaging systems @@ -6151,17 +5988,17 @@ components: an "apache" chart that is available globally, the names would need to encode that to be unique (ie. "repoA:apache" and "repoB:apache"). - title: Available package identifier plugin: $ref: "#/components/schemas/v1alpha1Plugin" description: >- - An AvailablePackageReference has the minimum information required to - uniquely + AvailablePackageReference + + + An AvailablePackageReference has the minimum information required to uniquely identify an available package. This is re-used on the summary and details of an available package. - title: AvailablePackageReference v1alpha1AvailablePackageSummary: type: object properties: @@ -6169,61 +6006,89 @@ components: $ref: "#/components/schemas/v1alpha1AvailablePackageReference" name: type: string - description: The name of the available package - title: Available package name + title: |- + Available package name + + The name of the available package latestVersion: $ref: "#/components/schemas/v1alpha1PackageAppVersion" iconUrl: type: string - description: A url for an icon. - title: Available package Icon URL + description: |- + Available package Icon URL + + A url for an icon. displayName: type: string - description: A name as displayed to users - title: Available package display name + title: |- + Available package display name + + A name as displayed to users shortDescription: type: string - description: A short description of the app provided by the package - title: Available package short description + title: |- + Available package short description + + A short description of the app provided by the package categories: type: array items: type: string - description: >- - A user-facing list of category names useful for creating richer user - interfaces. + title: >- + Available package categories + + + A user-facing list of category names useful for creating richer user interfaces. Plugins can choose not to implement this - title: Available package categories description: >- - An AvailablePackageSummary provides a summary of a package available for - installation + AvailablePackageSummary + + + An AvailablePackageSummary provides a summary of a package available for installation useful when aggregating many available packages. - title: AvailablePackageSummary + v1alpha1CanIResponse: + type: object + properties: + allowed: + type: boolean + title: |- + allowed + + True if operation is allowed + title: |- + CanIResponse + + Response for CanI operation v1alpha1CheckNamespaceExistsResponse: type: object properties: exists: type: boolean - description: Response for CheckNamespaceExists - title: CheckNamespaceExistsResponse + title: |- + CheckNamespaceExistsResponse + + Response for CheckNamespaceExists v1alpha1Context: type: object properties: cluster: type: string description: >- - A cluster name can be provided to target a specific cluster if - multiple + Cluster + + + A cluster name can be provided to target a specific cluster if multiple clusters are configured, otherwise all clusters will be assumed. - title: Cluster namespace: type: string description: >- - A namespace must be provided if the context of the operation is for - a resource + Namespace + + + A namespace must be provided if the context of the operation is for a resource or resources in a particular namespace. @@ -6234,9 +6099,10 @@ components: be filtered by any filtering options of the request. Plugins may choose to return Unimplemented for some queries for which we do not yet have a need. - title: Namespace - description: A Context specifies the context of the message - title: Context + title: |- + Context + + A Context specifies the context of the message v1alpha1CreateInstalledPackageRequest: type: object properties: @@ -6262,31 +6128,43 @@ components: on top of any values refs above, when relevant. reconciliationOptions: $ref: "#/components/schemas/v1alpha1ReconciliationOptions" - description: Request for CreateInstalledPackage - title: CreateInstalledPackageRequest + title: |- + CreateInstalledPackageRequest + + Request for CreateInstalledPackage v1alpha1CreateInstalledPackageResponse: type: object properties: installedPackageRef: $ref: "#/components/schemas/v1alpha1InstalledPackageReference" - description: Response for CreateInstalledPackage - title: CreateInstalledPackageResponse + title: |- + CreateInstalledPackageResponse + + Response for CreateInstalledPackage v1alpha1CreateNamespaceResponse: type: object - description: Response for CreateNamespace - title: CreateNamespaceResponse + title: |- + CreateNamespaceResponse + + Response for CreateNamespace v1alpha1CreateSecretResponse: type: object - description: Response for CreateSecret - title: CreateSecretResponse + title: |- + CreateSecretResponse + + Response for CreateSecret v1alpha1DeleteInstalledPackageResponse: type: object - description: Response for DeleteInstalledPackage - title: DeleteInstalledPackageResponse + title: |- + DeleteInstalledPackageResponse + + Response for DeleteInstalledPackage v1alpha1DeletePackageRepositoryResponse: type: object - description: Response for DeletePackageRepository - title: DeletePackageRepositoryResponse + title: |- + DeletePackageRepositoryResponse + + Response for DeletePackageRepository v1alpha1DockerCredentials: type: object properties: @@ -6308,37 +6186,51 @@ components: properties: query: type: string - description: Text query for the request - title: Text query + title: |- + Text query + + Text query for the request categories: type: array items: type: string - description: Collection of categories for the request - title: Categories + title: |- + Categories + + Collection of categories for the request repositories: type: array items: type: string - description: Collection of repositories where the packages belong to - title: Repositories + title: |- + Repositories + + Collection of repositories where the packages belong to pkgVersion: type: string - description: Package version for the request - title: Package version + title: |- + Package version + + Package version for the request appVersion: type: string - description: Packaged app version for the request - title: App version - description: FilterOptions available when requesting summaries - title: FilterOptions + title: |- + App version + + Packaged app version for the request + title: |- + FilterOptions + + FilterOptions available when requesting summaries v1alpha1GetAvailablePackageDetailResponse: type: object properties: availablePackageDetail: $ref: "#/components/schemas/v1alpha1AvailablePackageDetail" - description: Response for GetAvailablePackageDetail - title: GetAvailablePackageDetailResponse + title: |- + GetAvailablePackageDetailResponse + + Response for GetAvailablePackageDetail v1alpha1GetAvailablePackageSummariesResponse: type: object properties: @@ -6346,25 +6238,32 @@ components: type: array items: $ref: "#/components/schemas/v1alpha1AvailablePackageSummary" - description: List of AvailablePackageSummary - title: Available packages summaries + title: |- + Available packages summaries + + List of AvailablePackageSummary nextPageToken: type: string description: >- - This field represents the pagination token to retrieve the next page - of + Next page token + + + This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. - title: Next page token categories: type: array items: type: string - description: This optional field contains the distinct category names considering - the FilterOptions. - title: Categories - description: Response for GetAvailablePackageSummaries - title: GetAvailablePackageSummariesResponse + description: >- + Categories + + + This optional field contains the distinct category names considering the FilterOptions. + title: |- + GetAvailablePackageSummariesResponse + + Response for GetAvailablePackageSummaries v1alpha1GetAvailablePackageVersionsResponse: type: object properties: @@ -6373,6 +6272,9 @@ components: items: $ref: "#/components/schemas/v1alpha1PackageAppVersion" description: >- + Package app versions + + By default (when version_query is empty or ignored) the response should contain an ordered summary of versions including the most recent three @@ -6400,9 +6302,10 @@ components: If a version_query is present and the plugin chooses to support it, the full history of versions matching the version query should be returned. - title: Package app versions - description: Response for GetAvailablePackageVersions - title: GetAvailablePackageVersionsResponse + title: |- + GetAvailablePackageVersionsResponse + + Response for GetAvailablePackageVersions v1alpha1GetConfiguredPluginsResponse: type: object example: @@ -6414,17 +6317,23 @@ components: type: array items: $ref: "#/components/schemas/v1alpha1Plugin" - description: List of Plugin - title: Plugins - description: Response for GetConfiguredPlugins - title: GetConfiguredPluginsResponse + title: |- + Plugins + + List of Plugin + title: |- + GetConfiguredPluginsResponse + + Response for GetConfiguredPlugins v1alpha1GetInstalledPackageDetailResponse: type: object properties: installedPackageDetail: $ref: "#/components/schemas/v1alpha1InstalledPackageDetail" - description: Response for GetInstalledPackageDetail - title: GetInstalledPackageDetailResponse + title: |- + GetInstalledPackageDetailResponse + + Response for GetInstalledPackageDetail v1alpha1GetInstalledPackageResourceRefsResponse: type: object properties: @@ -6434,8 +6343,10 @@ components: type: array items: $ref: "#/components/schemas/v1alpha1ResourceRef" - description: Response for GetInstalledPackageResourceRefs - title: GetInstalledPackageResourceRefsResponse + title: |- + GetInstalledPackageResourceRefsResponse + + Response for GetInstalledPackageResourceRefs v1alpha1GetInstalledPackageSummariesResponse: type: object properties: @@ -6443,18 +6354,23 @@ components: type: array items: $ref: "#/components/schemas/v1alpha1InstalledPackageSummary" - description: List of InstalledPackageSummary - title: Installed packages summaries + title: |- + Installed packages summaries + + List of InstalledPackageSummary nextPageToken: type: string description: >- - This field represents the pagination token to retrieve the next page - of + Next page token + + + This field represents the pagination token to retrieve the next page of results. If the value is "", it means no further results for the request. - title: Next page token - description: Response for GetInstalledPackageSummaries - title: GetInstalledPackageSummariesResponse + title: |- + GetInstalledPackageSummariesResponse + + Response for GetInstalledPackageSummaries v1alpha1GetNamespaceNamesResponse: type: object properties: @@ -6462,17 +6378,23 @@ components: type: array items: type: string - description: The list of Namespace names. - title: NamespaceNames - description: Response for GetNamespaceNames - title: GetNamespaceNamesResponse + description: |- + NamespaceNames + + The list of Namespace names. + title: |- + GetNamespaceNamesResponse + + Response for GetNamespaceNames v1alpha1GetPackageRepositoryDetailResponse: type: object properties: detail: $ref: "#/components/schemas/v1alpha1PackageRepositoryDetail" - description: Response for GetPackageRepositoryDetail - title: GetPackageRepositoryDetailResponse + title: |- + GetPackageRepositoryDetailResponse + + Response for GetPackageRepositoryDetail v1alpha1GetPackageRepositorySummariesResponse: type: object properties: @@ -6481,8 +6403,10 @@ components: items: $ref: "#/components/schemas/v1alpha1PackageRepositorySummary" title: List of PackageRepositorySummary - description: Response for GetPackageRepositorySummaries - title: GetPackageRepositorySummariesResponse + title: |- + GetPackageRepositorySummariesResponse + + Response for GetPackageRepositorySummaries v1alpha1GetResourcesResponse: type: object properties: @@ -6491,6 +6415,9 @@ components: manifest: type: string description: >- + Manifest + + The current manifest of the requested resource. Initially the JSON manifest will be returned a json-encoded string, enabling the existing @@ -6500,7 +6427,6 @@ components: of resources, but we may in the future pull out further structured metadata into this message as needed. - title: Manifest v1alpha1GetSecretNamesResponse: type: object properties: @@ -6508,10 +6434,14 @@ components: type: object additionalProperties: $ref: "#/components/schemas/v1alpha1SecretType" - description: The list of Service Account names. - title: SecretNames - description: Response for GetSecretNames - title: GetSecretNamesResponse + description: |- + SecretNames + + The list of Service Account names. + title: |- + GetSecretNamesResponse + + Response for GetSecretNames v1alpha1GetServiceAccountNamesResponse: type: object properties: @@ -6519,10 +6449,14 @@ components: type: array items: type: string - description: The list of Service Account names. - title: ServiceAccountNames - description: Response for GetServiceAccountNames - title: GetServiceAccountNamesResponse + description: |- + ServiceAccountNames + + The list of Service Account names. + title: |- + GetServiceAccountNamesResponse + + Response for GetServiceAccountNames v1alpha1InstalledPackageDetail: type: object properties: @@ -6532,23 +6466,29 @@ components: $ref: "#/components/schemas/v1alpha1VersionReference" name: type: string - description: The name given to the installed package - title: Installed package name + title: |- + Installed package name + + The name given to the installed package currentVersion: $ref: "#/components/schemas/v1alpha1PackageAppVersion" valuesApplied: type: string - description: The values applied currently for the installed package. - title: ValuesApplied + description: |- + ValuesApplied + + The values applied currently for the installed package. reconciliationOptions: $ref: "#/components/schemas/v1alpha1ReconciliationOptions" status: $ref: "#/components/schemas/v1alpha1InstalledPackageStatus" postInstallationNotes: type: string - description: Optional notes generated by package and intended for the user post - installation. - title: PostInstallationNotes + description: >- + PostInstallationNotes + + + Optional notes generated by package and intended for the user post installation. availablePackageRef: $ref: "#/components/schemas/v1alpha1AvailablePackageReference" latestMatchingVersion: @@ -6558,11 +6498,12 @@ components: customDetail: $ref: "#/components/schemas/protobufAny" description: >- - An InstalledPackageDetail includes details about the installed package - that are + InstalledPackageDetail + + + An InstalledPackageDetail includes details about the installed package that are typically useful when presenting a single installed package. - title: InstalledPackageDetail v1alpha1InstalledPackageReference: type: object properties: @@ -6576,28 +6517,35 @@ components: plugin: $ref: "#/components/schemas/v1alpha1Plugin" description: >- - An InstalledPackageReference has the minimum information required to - uniquely + InstalledPackageReference + + + An InstalledPackageReference has the minimum information required to uniquely identify an installed package. - title: InstalledPackageReference v1alpha1InstalledPackageStatus: type: object properties: ready: type: boolean - description: An indication of whether the installation is ready or not - title: Ready + title: |- + Ready + + An indication of whether the installation is ready or not reason: $ref: "#/components/schemas/v1alpha1InstalledPackageStatusStatusReason" userReason: type: string - description: Optional text to return for user context, which may be plugin - specific. - title: UserReason - description: An InstalledPackageStatus reports on the current status of the - installation. - title: InstalledPackageStatus + description: >- + UserReason + + + Optional text to return for user context, which may be plugin specific. + description: >- + InstalledPackageStatus + + + An InstalledPackageStatus reports on the current status of the installation. v1alpha1InstalledPackageStatusStatusReason: type: string enum: @@ -6608,9 +6556,10 @@ components: - STATUS_REASON_PENDING default: STATUS_REASON_UNSPECIFIED description: |- + StatusReason + Generic reasons why an installed package may be ready or not. These should make sense across different packaging plugins. - title: StatusReason v1alpha1InstalledPackageSummary: type: object properties: @@ -6618,26 +6567,34 @@ components: $ref: "#/components/schemas/v1alpha1InstalledPackageReference" name: type: string - description: A name given to the installation of the package (eg. - "my-postgresql-for-testing"). - title: Name + description: >- + Name + + + A name given to the installation of the package (eg. "my-postgresql-for-testing"). pkgVersionReference: $ref: "#/components/schemas/v1alpha1VersionReference" currentVersion: $ref: "#/components/schemas/v1alpha1PackageAppVersion" iconUrl: type: string - description: A url for an icon. - title: Installed package icon URL + description: |- + Installed package icon URL + + A url for an icon. pkgDisplayName: type: string - description: The package name as displayed to users (provided by the package, eg. - "PostgreSQL") - title: PackageDisplayName + title: >- + PackageDisplayName + + + The package name as displayed to users (provided by the package, eg. "PostgreSQL") shortDescription: type: string - description: A short description of the package (provided by the package) - title: ShortDescription + title: |- + ShortDescription + + A short description of the package (provided by the package) latestMatchingVersion: $ref: "#/components/schemas/v1alpha1PackageAppVersion" latestVersion: @@ -6645,22 +6602,29 @@ components: status: $ref: "#/components/schemas/v1alpha1InstalledPackageStatus" description: |- + InstalledPackageSummary + An InstalledPackageSummary provides a summary of an installed package useful when aggregating many installed packages. - title: InstalledPackageSummary v1alpha1Maintainer: type: object properties: name: type: string - description: A maintainer name - title: Maintainer name + title: |- + Maintainer name + + A maintainer name email: type: string - description: A maintainer email - title: Maintainer email - description: Maintainers for the package. - title: Maintainer + title: |- + Maintainer email + + A maintainer email + description: |- + Maintainer + + Maintainers for the package. v1alpha1OpaqueCredentials: type: object properties: @@ -6675,15 +6639,21 @@ components: properties: pkgVersion: type: string - description: Version of the package itself - title: Package version + title: |- + Package version + + Version of the package itself appVersion: type: string - description: Version of the packaged application - title: Application version - description: PackageAppVersion conveys both the package version and the packaged app - version. - title: Package AppVersion + title: |- + Application version + + Version of the packaged application + description: >- + Package AppVersion + + + PackageAppVersion conveys both the package version and the packaged app version. v1alpha1PackageRepositoryAuth: type: object properties: @@ -6721,9 +6691,11 @@ components: This may be needed if the host of the advertised chart URLs in the index differs from the defined URL. Optional - description: >- - Authentication/authorization to provide client's identity when - connecting + title: >- + PackageRepositoryAuth + + + Authentication/authorization to provide client's identity when connecting to a package repository. @@ -6751,9 +6723,8 @@ components: a given plug-in may or may not support a given authentication type. For example - - direct-helm plug-in does not currently support (6), while flux does - - flux plug-in does not support (3) or (4) while direct-helm does - title: PackageRepositoryAuth + - direct-helm plug-in does not currently support (6), while flux does + - flux plug-in does not support (3) or (4) while direct-helm does v1alpha1PackageRepositoryDetail: type: object properties: @@ -6775,9 +6746,9 @@ components: type: string description: A URL identifying the package repository location. interval: - type: integer - format: int64 - title: The interval at which to check the upstream for updates (in seconds) + type: string + title: The interval at which to check the upstream for updates (in + time+unit) tlsConfig: $ref: "#/components/schemas/v1alpha1PackageRepositoryTlsConfig" auth: @@ -6800,26 +6771,33 @@ components: plugin: $ref: "#/components/schemas/v1alpha1Plugin" description: |- + PackageRepositoryReference + A PackageRepositoryReference has the minimum information required to uniquely identify a package repository. - title: PackageRepositoryReference v1alpha1PackageRepositoryStatus: type: object properties: ready: type: boolean - description: An indication of whether the repository is ready or not - title: Ready + title: |- + Ready + + An indication of whether the repository is ready or not reason: $ref: "#/components/schemas/v1alpha1PackageRepositoryStatusStatusReason" userReason: type: string - description: Optional text to return for user context, which may be plugin - specific. - title: UserReason - description: A PackageRepositoryStatus reports on the current status of the - repository. - title: PackageRepositoryStatus + description: >- + UserReason + + + Optional text to return for user context, which may be plugin specific. + description: >- + PackageRepositoryStatus + + + A PackageRepositoryStatus reports on the current status of the repository. v1alpha1PackageRepositoryStatusStatusReason: type: string enum: @@ -6829,9 +6807,10 @@ components: - STATUS_REASON_PENDING default: STATUS_REASON_UNSPECIFIED description: |- + StatusReason + Generic reasons why a package repository may be ready or not. These should make sense across different packaging plugins. - title: StatusReason v1alpha1PackageRepositorySummary: type: object properties: @@ -6854,6 +6833,10 @@ components: description: URL identifying the package repository location. status: $ref: "#/components/schemas/v1alpha1PackageRepositoryStatus" + requiresAuth: + type: boolean + description: existence of any authentication parameters for connecting to a + repository. title: PackageRepositorySummary v1alpha1PackageRepositoryTlsConfig: type: object @@ -6875,29 +6858,34 @@ components: properties: pageToken: type: string - description: The client uses this field to request a specific page of the list - results. - title: Page token + description: >- + Page token + + + The client uses this field to request a specific page of the list results. pageSize: type: integer format: int32 description: >- - Clients use this field to specify the maximum number of results to - be + Page size + + + Clients use this field to specify the maximum number of results to be returned by the server. The server may further constrain the maximum number of results returned in a single page. If the page_size is 0, the server will decide the number of results to be returned. - title: Page size description: >- + PaginationOptions + + The PaginationOptions based on the example proto at: https://cloud.google.com/apis/design/design_patterns#list_pagination just encapsulated in a message so it can be reused on different request messages. - title: PaginationOptions v1alpha1Plugin: type: object example: @@ -6906,50 +6894,60 @@ components: properties: name: type: string - description: The name of the plugin, such as `fluxv2.packages` or - `kapp_controller.packages`. - title: Plugin name + description: >- + Plugin name + + + The name of the plugin, such as `fluxv2.packages` or `kapp_controller.packages`. version: type: string - description: The version of the plugin, such as v1alpha1 - title: Plugin version - description: A plugin can implement multiple services and multiple versions of a - service. - title: Plugin + title: |- + Plugin version + + The version of the plugin, such as v1alpha1 + description: >- + Plugin + + + A plugin can implement multiple services and multiple versions of a service. v1alpha1ReconciliationOptions: type: object properties: interval: - type: integer - format: int32 - description: The interval with which the package is checked for reconciliation - (in seconds) - title: Reconciliation Interval + type: string + title: >- + Reconciliation Interval + + + The interval with which the package is checked for reconciliation (in time+unit) suspend: type: boolean - description: |- + title: |- + Suspend + Whether reconciliation should be suspended until otherwise enabled. This can be utilized to e.g. temporarily ignore chart changes, and prevent a Helm release from getting upgraded - title: Suspend serviceAccountName: type: string description: >- - A name for a service account in the same namespace which should be - used + ServiceAccountName + + + A name for a service account in the same namespace which should be used to perform the reconciliation. - title: ServiceAccountName description: >- - ReconciliationOptions enable specifying standard fields for backends - that continuously + ReconciliationOptions + + + ReconciliationOptions enable specifying standard fields for backends that continuously reconcile a package install as new matching versions are released. Most of the naming is from the flux HelmReleaseSpec though it maps directly to equivalent fields on Carvel's InstalledPackage. - title: ReconciliationOptions v1alpha1ResourceRef: type: object properties: @@ -6983,20 +6981,23 @@ components: that install resources in other namespaces for special reasons. description: >- - A reference to a Kubernetes resource related to a specific installed - package. + Resource reference + + + A reference to a Kubernetes resource related to a specific installed package. The context (cluster) for each resource is that of the related installed package. - title: Resource reference v1alpha1RollbackInstalledPackageResponse: type: object properties: installedPackageRef: $ref: "#/components/schemas/v1alpha1InstalledPackageReference" - description: Response for RollbackInstalledPackage - title: RollbackInstalledPackageResponse + title: |- + RollbackInstalledPackageResponse + + Response for RollbackInstalledPackage v1alpha1SecretKeyReference: type: object properties: @@ -7038,7 +7039,10 @@ components: - SECRET_TYPE_TLS - SECRET_TYPE_BOOTSTRAP_TOKEN default: SECRET_TYPE_OPAQUE_UNSPECIFIED - description: >- + title: >- + SecretType + + The type of secret. Currently Kubeapps itself only deals with OPAQUE and docker config json secrets, but we define all so we can correctly @@ -7046,7 +7050,6 @@ components: list the secret names with their types. See https://kubernetes.io/docs/concepts/configuration/secret/#secret-types - title: SecretType v1alpha1SshCredentials: type: object properties: @@ -7072,15 +7075,19 @@ components: properties: installedPackageRef: $ref: "#/components/schemas/v1alpha1InstalledPackageReference" - description: Response for UpdateInstalledPackage - title: UpdateInstalledPackageResponse + title: |- + UpdateInstalledPackageResponse + + Response for UpdateInstalledPackage v1alpha1UpdatePackageRepositoryResponse: type: object properties: packageRepoRef: $ref: "#/components/schemas/v1alpha1PackageRepositoryReference" - description: Response for UpdatePackageRepository - title: UpdatePackageRepositoryResponse + title: |- + UpdatePackageRepositoryResponse + + Response for UpdatePackageRepository v1alpha1UsernamePassword: type: object properties: @@ -7096,19 +7103,21 @@ components: properties: version: type: string - description: >- - The format of the version constraint depends on the backend. For - example, + title: >- + Version + + + The format of the version constraint depends on the backend. For example, for a flux v2 and Carvel it's a semver expression, such as ">=10.3 < 10.4" - title: Version description: >- - A VersionReference defines a version or constraint limiting matching - versions. + VersionReference + + + A VersionReference defines a version or constraint limiting matching versions. The reason it is a separate message is so that in the future we can add other fields as necessary (such as something similar to Carvel's `prereleases` option to its versionSelection). - title: VersionReference diff --git a/site/content/docs/latest/reference/developer/release-process.md b/site/content/docs/latest/reference/developer/release-process.md index 8d3efd36697..08d0bc08283 100644 --- a/site/content/docs/latest/reference/developer/release-process.md +++ b/site/content/docs/latest/reference/developer/release-process.md @@ -85,18 +85,21 @@ As per the introduction of the new Kubeapps APIs service, it is based upon autom ```bash # You need to have the latest buf binary installed, if not, go to https://docs.buf.build/installation/ -buf mod update cmd/kubeapps-apis/ +buf mod update cmd/kubeapps-apis/ ``` - Next, the autogenerated code ought to be regenerated. Note that some of the fronted code files might not comply with the `prettier` rules, therefore, triggering the linter may be required. ```bash # You need to have the latest buf binary installed, if not, go to https://docs.buf.build/installation/ -cd cmd/kubeapps-apis +cd cmd/kubeapps-apis make generate -npx prettier --write ../../dashboard/src/ + +npx prettier --write ../../dashboard/src/ ``` +As part of this process, the [autogenerated API documentation](/~https://github.com/vmware-tanzu/kubeapps/blob/main/cmd/kubeapps-apis/docs/kubeapps-apis.swagger.json) may have changed. If so, it _must_ be updated in the [API docs we bundle in the dashboard](/~https://github.com/vmware-tanzu/kubeapps/blob/main/dashboard/public/openapi.yaml). To do so, the autogenerated file should be first converted to OpenAPI 3 (using, for instance, [this tool](https://mermade.org.uk/openapi-converter)). Then, just copy the `paths` and `components` sections from the generated file to the dashboard's `openapi.yaml` file. Finally, note that all the paths in the `openapi.yaml` file _must_ be prefixed with `/apis/`, so that the interactive API docs work properly. + > As part of this release process, the buf.lock dependencies _must_ be updated to the latest versions. In case of a major version, the change _should_ be tracked in a separate PR. ### 0.4 - Upgrading the code dependencies