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