universe.catalog.v1

Note

This API is available for CloudAdmin and Tenants

Proto file and generated GO client for the API can be found in universe-api repo

This API is served by universe-infra-catalog-manager and provides a way to deploy Helm charts in infrastructure cluster.

The Catalog API is available both for Tenant and Admin. Tenants are identified by an additional GRPC header.

Installing CRDs via Catalog API is not supported.

The handling of the HelmRepository and Helm Release CRs are handled by Flux controllers:

Note

Tenant Helm charts are constrained by a Service Account with limited permissions allowing creating objects only in the Tenant namespace. In addition, any Kubernetes workload created by the Helm chart will have a Node Selector limiting to Nodes associated with the Tenant.

Check Manual GRPC API usage doc before start.

Note

Replace $API_GW_ADDRESS with address of iCP API GW in your environment

Source API examples

Here some examples using ‘grpcurl’ tool to access the API:

List Helm Repositories:

Copy
Copied!
            

grpcurl -cacert=ca.crt -cert=admin.crt -key=admin.key -servername api-gateway.local \ -proto universe/catalog/v1/source.proto $API_GW_ADDRESS \ universe.catalog.v1.SourceService.ListHelmRepository

Create Helm Repository:

The Helm Repository support HTTP, HTTPS, or OCI (Open Container Initiative) image registry servers.

For OCI repositories, the URL should start with “oci://”.

Copy
Copied!
            

grpcurl -cacert=ca.crt -cert=admin.crt -key=admin.key -servername api-gateway.local \ -d '{"helm_repository" :{"name": "ngc", "url": "https://helm.ngc.nvidia.com/nvidia"} }' \ -proto universe/catalog/v1/source.proto $API_GW_ADDRESS \ universe.catalog.v1.SourceService.CreateHelmRepository

Create Helm Repository with authentication:

For Helm Repositories that require authentication, first create Credentials and then create the Helm Repository with reference to them.

Create Credentials:

Copy
Copied!
            

grpcurl -cacert=ca.crt -cert=admin.crt -key=admin.key -servername api-gateway.local \ -d '{"cred": {"name": "doca-secret", "user_name": "$oauthtoken", "password": "my-password"}}' -proto universe/catalog/v1/source.proto $API_GW_ADDRESS \ universe.catalog.v1.SourceService.CreateCredential

Create Helm Repository with reference to credentials:

Copy
Copied!
            

grpcurl -cacert=ca.crt -cert=admin.crt -key=admin.key -servername api-gateway.local \ -d '{"helm_repository" :{"name": "ngc", "url": "https://helm.ngc.nvidia.com/nvidia", "credential_ref": {"name": "doca-secret"}}}' \ -proto universe/catalog/v1/source.proto $API_GW_ADDRESS \ universe.catalog.v1.SourceService.CreateHelmRepository

Get Helm Repository:

Copy
Copied!
            

grpcurl -cacert=ca.crt -cert=admin.crt -key=admin.key -servername api-gateway.local \ -d '{"name": "doca"}' universe.catalog.v1.SourceService.GetHelmRepository -proto universe/catalog/v1/source.proto $API_GW_ADDRESS \

Delete Helm Repository:

Copy
Copied!
            

grpcurl -cacert=ca.crt -cert=admin.crt -key=admin.key -servername api-gateway.local \ -d '{"name": "doca"}' universe.catalog.v1.SourceService.DeleteHelmRepository -proto universe/catalog/v1/source.proto $API_GW_ADDRESS \

Create Image Registry Credentials:

In case that a Helm Chart deploys containers which images are hosted on a container registry server that requires authentication, it is possible to create a Secret to pull these images via CreateImageRegistryCredential API.

Note that it will be necessary to specify this secret name as ImagePullSecrets in the values of the HelmRelease.

Copy
Copied!
            

grpcurl -cacert=ca.crt -cert=admin.crt -key=admin.key -servername api-gateway.local \ -d '{"cred": {"name": "doca-nvstaging", "server":"nvcr.io", "user_name": "$oauthtoken", "password": "my-password"}}' -proto universe/catalog/v1/source.proto $API_GW_ADDRESS \ universe.catalog.v1.SourceService.CreateImageRegistryCredential

Helm API examples

Here some examples using ‘grpcurl’ tool to access the API:

List Helm Releases:

Copy
Copied!
            

grpcurl -cacert=ca.crt -cert=admin.crt -key=admin.key -servername api-gateway.local \ -proto universe/catalog/v1/helm.proto $API_GW_ADDRESS \ universe.catalog.v1.HelmService.ListRelease

Create Helm Release:

Note that the “source_ref” should be the name of a HelmRepository where the Helm Chart is hosted.

Copy
Copied!
            

grpcurl -cacert=ca.crt -cert=admin.crt -key=admin.key -servername api-gateway.local \ -d '{"release":{"name": "flow-inspector", "chart": "doca-flow-inspector", "version": "0.1.0","source_ref":{"name": "doca-nvstaging"}}}' \ -proto universe/catalog/v1/helm.proto $API_GW_ADDRESS \ universe.catalog.v1.HelmService.CreateRelease

Create Helm Release with Values file:

Helm support providing a yaml file to override values in order to customize the deployed chart.

Create Values:

In this example, a nodeSelector and a Secret to pull images are added. Note that the fields supported in the Values files are specific to each Helm Chart.

Copy
Copied!
            

cat << EOF | tee values.yaml nodeSelector: role: storage imagePullSecrets: - name: doca-nvstaging EOF # put base64 encoded values file to VALUES shell variable VALUES=$(cat values.yaml | base64 -w0) # -d @ argument for grpcurl mean read arguments from STDIN # use content of VALUES shell variable as values grpcurl -cacert=ca.crt -cert=admin.crt -key=admin.key -servername api-gateway.local \ -d @ -proto universe/catalog/v1/helm.proto $API_GW_ADDRESS \ universe.catalog.v1.HelmService.CreateValues << EOM {"name": "app-values", "values" :"$VALUES"} EOM

Create Helm Release with Values reference:

Copy
Copied!
            

cat << EOF | tee release.json { "release":{ "name":"flow-inspector", "chart":"doca-flow-inspector", "version":"0.1.0", "source_ref":{ "name":"doca-nvstaging" }, "values_ref":{ "name":"app-values" } } } EOF grpcurl -cacert=ca.crt -cert=admin.crt -key=admin.key -servername api-gateway.local \ -d "`cat release.json`" \ -proto universe/catalog/v1/helm.proto $API_GW_ADDRESS \ universe.catalog.v1.HelmService.CreateRelease

Get Helm Release:

Copy
Copied!
            

grpcurl -cacert=ca.crt -cert=admin.crt -key=admin.key -servername api-gateway.local \ -proto universe/catalog/v1/helm.proto $API_GW_ADDRESS \ -d '{"name": "flow-inspector"}' universe.catalog.v1.HelmService.GetRelease

Delete Helm Release:

Copy
Copied!
            

grpcurl -cacert=ca.crt -cert=admin.crt -key=admin.key -servername api-gateway.local \ -proto universe/catalog/v1/helm.proto $API_GW_ADDRESS \ -d '{"name": "flow-inspector"}' universe.catalog.v1.HelmService.DeleteRelease

Source API

Copy
Copied!
            

syntax = "proto3"; package universe.catalog.v1; import "universe/common/v1/common.proto"; // SourceService is a service used to perform CRUD operations on Source objects like HelmRepository // The following client metadata fields are used: // "tenant-id" (optional): tenant identifier service SourceService { // create a new Helm repository, return error if Helm Repository already exist rpc CreateHelmRepository(CreateHelmRepositoryRequest) returns (CreateHelmRepositoryResponse) {} // delete existing Helm repository rpc DeleteHelmRepository(DeleteHelmRepositoryRequest) returns (DeleteHelmRepositoryResponse) {} // get specific instance of Helm repository rpc GetHelmRepository(GetHelmRepositoryRequest) returns (GetHelmRepositoryResponse) {} // list Helm repositories rpc ListHelmRepository(ListHelmRepositoryRequest) returns (ListHelmRepositoryResponse) {} // create a new Credential, to be used to access a Helm repository rpc CreateCredential(CreateCredentialRequest) returns (CreateCredentialResponse) {} // delete existing Credential rpc DeleteCredential(DeleteCredentialRequest) returns (DeleteCredentialResponse) {} // create a new ImageRegistryCredential, to be used as imagePullSecrets in a Helm.CreateValues request to access a container image registry server rpc CreateImageRegistryCredential(CreateImageRegistryCredentialRequest) returns (CreateImageRegistryCredentialResponse) {} // delete existing ImageRegistryCredential rpc DeleteImageRegistryCredential(DeleteImageRegistryCredentialRequest) returns (DeleteImageRegistryCredentialResponse) {} } // Credential is a message that contains a Credential object containing user name and password message Credential { string name = 1; string user_name = 2; string password = 3; } // createCredentialRequest is used to create a Credential in the infrastructure cluster message CreateCredentialRequest { // full Credentials object Credential cred = 1; } // keep empty for now, later on rpc may be extended message CreateCredentialResponse {} // deleteCredentialRequest is used to delete a Credential in the infrastructure cluster message DeleteCredentialRequest { // name of a Credentials to remove string credential_name = 1; } // keep empty for now, later on rpc may be extended message DeleteCredentialResponse {} // ImageRegistryCredential is a message that contains a Credential object containing server name, user name and password // to be used for connecting to container image registry server requiring authentication message ImageRegistryCredential { string name = 1; string server = 2; string user_name = 3; string password = 4; } // createCredentialRequest is used to create a ImageRegistryCredential in the infrastructure cluster message CreateImageRegistryCredentialRequest { // full ImageRegistry object ImageRegistryCredential cred = 1; } // keep empty for now, later on rpc may be extended message CreateImageRegistryCredentialResponse {} // deleteCredentialRequest is used to delete a ImageRegistryCredential in the infrastructure cluster message DeleteImageRegistryCredentialRequest { // name of a ImageRegistryCredentials to remove string credential_name = 1; } // keep empty for now, later on rpc may be extended message DeleteImageRegistryCredentialResponse {} // ---------- // Helm repository // ---------- // artifact is a message that contains the output of a Source reconciliation message Artifact { // checksum is the SHA256 checksum of the Artifact file string checksum = 1; // last_update_time is the timestamp corresponding to the last update of the Artifact. string last_update_time = 2; // path is the relative file path of the Artifact string path = 3; // revision is a human-readable identifier traceable in the origin source // system. It can be a Git commit SHA, Git tag, a Helm chart version, etc. string revision = 4; // url is the HTTP address of the Artifact as exposed by the controller managing the Source. string url = 5; } // HelmRepository is a message that contains a Helm repository object and its fields message HelmRepository { // HelmRepository.Status is a message that contains a Helm repository Status object and its fields message Status { // Artifact is a message that contains the last successful Helm repository reconciliation Artifact artifact = 1; // conditions reflecting the current state of the Helm repository repeated common.v1.Condition conditions = 2; } // unique name for Helm repository string name = 1; // URL of the Helm repository. For OCI repository, URL must be prefixed with "oci://". Otherwise, "http://" or "https://" string url = 2; // reference to credentials to use for accessing the Helm repository optional common.v1.LocalObjectRef credential_ref = 3; // the observed state of the Helm repository optional Status status = 4; } // message for create Helm repository request message CreateHelmRepositoryRequest { // full Helm repository object HelmRepository helm_repository = 1; } // message for response of the create request message CreateHelmRepositoryResponse {} // message for delete request message DeleteHelmRepositoryRequest { // name of a Helm repository to remove string name = 1; } // message for response of the delete request message DeleteHelmRepositoryResponse {} // message for response of the get request message GetHelmRepositoryRequest { // name of a Helm repository to retrieve string name = 1; } // message for response of the get request message GetHelmRepositoryResponse { // contains single Helm repository HelmRepository helm_repository = 1; } // message for list request // no parameters supported for now message ListHelmRepositoryRequest {} // message for response of the list request message ListHelmRepositoryResponse { // list of Helm repositories repeated HelmRepository helm_repositories = 1; }

Helm API

Copy
Copied!
            

syntax = "proto3"; package universe.catalog.v1; import "universe/common/v1/common.proto"; // HelmService is a service used to perform CRUD operations on Helm objects to deploy Helm chart on Infra Cluster // The following client metadata fields are used: // "tenant-id" (optional): tenant identifier service HelmService { // create a new Helm Values, return error if Values already exist rpc CreateValues(CreateValuesRequest) returns (CreateValuesResponse) {} // update existing Helm Values, return error if Values does not exist rpc UpdateValues(UpdateValuesRequest) returns (UpdateValuesResponse) {} // delete existing Helm Values rpc DeleteValues(DeleteValuesRequest) returns (DeleteValuesResponse) {} // create a new Release, return error if Release already exist rpc CreateRelease(CreateReleaseRequest) returns (CreateReleaseResponse) {} // delete existing Release rpc DeleteRelease(DeleteReleaseRequest) returns (DeleteReleaseResponse) {} // get specific instance of Release rpc GetRelease(GetReleaseRequest) returns (GetReleaseResponse) {} // list Releases rpc ListRelease(ListReleaseRequest) returns (ListReleaseResponse) {} } // message for create Values request message CreateValuesRequest { // unique name for Values string name = 1; // bytes representation of yaml file to be passed as values to Helm release bytes values = 2; } // keep empty for now, later on rpc may be extended message CreateValuesResponse {} // message for update request message UpdateValuesRequest { // name of Values to update string name = 1; // bytes representation of yaml file to be passed as values to Helm release bytes values = 2; } // keep empty for now, later on rpc may be extended message UpdateValuesResponse {} // message for delete request message DeleteValuesRequest { // name of a Values to remove string name = 1; } // keep empty for now, later on rpc may be extended message DeleteValuesResponse {} // Release is a message that contains a Helm release object and its fields message Release { // Release.Status is a message that contains a Release Status object and its fields message Status { // conditions reflecting the current state of the Release repeated common.v1.Condition condition = 1; } // unique name for Release string name = 1; // The name or path the Helm chart is available at in the source_ref string chart = 2; // The reference of the Source the chart is available at common.v1.LocalObjectRef source_ref = 3; // version semver expression, defaults to latest when omitted optional string version = 4; // The reference of resource containing Helm values for this Release optional common.v1.LocalObjectRef values_ref = 5; // the observed state of the Helm release optional Status status = 6; } // message for create Release request message CreateReleaseRequest { // full Release object Release release = 1; } // keep empty for now, later on rpc may be extended message CreateReleaseResponse {} // message for delete request message DeleteReleaseRequest { // name of a Release to remove string name = 1; } // keep empty for now, later on rpc may be extended message DeleteReleaseResponse {} // message for response of the get request message GetReleaseRequest { // name of a Release to retrieve string name = 1; } // message for response of the get request message GetReleaseResponse { // contains single Release Release release = 1; } // message for list request // no parameters supported for now message ListReleaseRequest {} // message for response of the list request message ListReleaseResponse { // list of Releases repeated Release releases = 1; }

Common Messages

Copy
Copied!
            

syntax = "proto3"; package universe.common.v1; message ObjectRef { string name = 1; optional string namespace = 2; } // Contains enough information to locate referenced object inside same namespace message LocalObjectRef { // Name of the referent string name = 1; } // Condition is a message that contains a Condition object and its fields message Condition { // Status is an enum status of the condition, one of True, False, Unknown. enum Status { // invalid value STATUS_UNSPECIFIED = 0; // condition is True STATUS_TRUE = 1; // condition is False STATUS_FALSE = 2; // condition is Unknown STATUS_UNKNOWN = 3; } // type of condition string type = 1; // status of condition Status status = 2; // time of last transition of status string last_transition_time = 3; // reason of condition status string reason = 4; // message describing the status optional string message = 5; }

Previous universe.admin.workload.v1
Next Examples
© Copyright 2023, NVIDIA. Last updated on Feb 7, 2024.