universe.catalog.v1
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:
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.
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:
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://”.
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:
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:
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:
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:
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.
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:
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.
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.
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:
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:
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:
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
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
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
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;
}