repositories.proto

// Copyright 2021-2023 the Kubeapps contributors.
// SPDX-License-Identifier: Apache-2.0

syntax = "proto3";
package kubeappsapis.core.packages.v1alpha1;
option go_package = "github.com/vmware-tanzu/kubeapps/cmd/kubeapps-apis/gen/core/packages/v1alpha1";

import "google/api/annotations.proto";
import "google/protobuf/any.proto";
import "kubeappsapis/core/packages/v1alpha1/packages.proto";
import "kubeappsapis/core/plugins/v1alpha1/plugins.proto";
import "protoc-gen-openapiv2/options/annotations.proto";

// This protobuf file defines the request and response types for API calls
// interacting with repositories, as well as the RepositoriesService to be implemented.

// Each repositories v1alpha1 plugin must implement at least the following rpcs:
//
service RepositoriesService {
  rpc AddPackageRepository(AddPackageRepositoryRequest) returns (AddPackageRepositoryResponse) {
    option (google.api.http) = {
      post: "/core/packages/v1alpha1/repositories"
      body: "*"
    };
   }

  rpc GetPackageRepositoryDetail(GetPackageRepositoryDetailRequest) returns (GetPackageRepositoryDetailResponse) {
    option (google.api.http) = {
      get: "/core/packages/v1alpha1/repositories/plugin/{package_repo_ref.plugin.name}/{package_repo_ref.plugin.version}/c/{package_repo_ref.context.cluster}/ns/{package_repo_ref.context.namespace}/{package_repo_ref.identifier=**}"
    };
   }

  rpc GetPackageRepositorySummaries(GetPackageRepositorySummariesRequest) returns (GetPackageRepositorySummariesResponse) {
    option (google.api.http) = {
      get: "/core/packages/v1alpha1/repositories"
    };
  }

  rpc UpdatePackageRepository(UpdatePackageRepositoryRequest) returns (UpdatePackageRepositoryResponse) {
    option (google.api.http) = {
      put: "/core/packages/v1alpha1/repositories/plugin/{package_repo_ref.plugin.name}/{package_repo_ref.plugin.version}/c/{package_repo_ref.context.cluster}/ns/{package_repo_ref.context.namespace}/{package_repo_ref.identifier=**}"
      body: "*"
     };
  }

  rpc DeletePackageRepository(DeletePackageRepositoryRequest) returns (DeletePackageRepositoryResponse) {
    option (google.api.http) = {
      delete: "/core/packages/v1alpha1/repositories/plugin/{package_repo_ref.plugin.name}/{package_repo_ref.plugin.version}/c/{package_repo_ref.context.cluster}/ns/{package_repo_ref.context.namespace}/{package_repo_ref.identifier=**}"
    };
  }

  rpc GetPackageRepositoryPermissions(GetPackageRepositoryPermissionsRequest) returns (GetPackageRepositoryPermissionsResponse) {
    option (google.api.http) = {
      get: "/core/packages/v1alpha1/repositories/c/{context.cluster}/permissions"
    };
  }
}

// Standard request and response messages for each required function are defined
// below for import and re-use.

// -- Start definitions of the request messages --

// AddPackageRepositoryRequest
//
// Request for AddPackageRepository
message AddPackageRepositoryRequest {
  // The target context where the package repository is intended to be
  // installed.
  Context context = 1;

  // A user-provided name for the package repository (e.g. bitnami)
  string name = 2;

  // A user-provided description. Optional
  string description = 3;

  // Whether this repository is global or namespace-scoped. Optional.
  // By default, the value is false, i.e. the repository is global
  bool namespace_scoped = 4;

  // Package storage type
  // In general, each plug-in will define an acceptable set of valid types
  // - for direct helm plug-in valid values are: "helm" and "oci"
  // - 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
  string type = 5;

  // A URL identifying the package repository location. Must contain at
  // least a protocol and host
  string url = 6;

  // The interval at which to check the upstream for updates (in time+unit)
  // Some plugins may, additionally, support other formats, for instance,
  // a cron expression.
  // e.g., "*/10 * * * *" will be equivalent to "10m"
  // Optional. Defaults to 10m if not specified
  string interval = 7;

  // TLS-specific parameters for connecting to a repository. Optional
  PackageRepositoryTlsConfig tls_config = 8;

  // authentication parameters for connecting to a repository. Optional
  PackageRepositoryAuth auth = 9;

  // The plugin used to interact with this package repository.
  // This field should be omitted when the request is in the context of a
  // specific plugin.
  kubeappsapis.core.plugins.v1alpha1.Plugin plugin = 10;

  // Custom data added by the plugin
  // A plugin can define custom details for data which is not yet, or
  // never will be specified in the core AddPackageRepositoryRequest
  // fields. The use of an `Any` field means that each plugin can define
  // the structure of this message as required, while still satisfying the
  // core interface.
  // See https://developers.google.com/protocol-buffers/docs/proto3#any
  // Just for reference, some of the examples that have been chosen not to
  // be part of the core API but rather plugin-specific details are:
  //   direct-helm:
  //      - image pull secrets
  //      - list of oci repositories
  //      - filter rules
  //      - sync job pod template
  google.protobuf.Any custom_detail = 11;
}

// PackageRepositoryTlsConfig
//
message PackageRepositoryTlsConfig {
  // whether or not to skip TLS verification
  // note that fluxv2 does not currently support this and will raise an
  // error should this flag be set to true
  bool insecure_skip_verify = 1;

  oneof package_repo_tls_config_one_of {
    // certificate authority. Optional
    string cert_authority = 2;

    // a reference to an existing secret that contains custom CA
    SecretKeyReference secret_ref = 3;
  }
}

// PackageRepositoryAuth
//
// Authentication/authorization to provide client's identity when connecting
// to a package repository.
// There are 6 total distinct use cases we may support:
// 1) None (Public)
// 2) Basic Auth
// 3) Bearer Token
// 4) Custom Authorization Header
// 5) Docker Registry Credentials (for OCI only)
// 6) TLS certificate and key
//
// Note that (1)-(4) may be done over HTTP or HTTPs without any custom
// certificates or certificate authority
// (1) is handled by not not having PackageRepositoryAuth field on
//     the parent object
// 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
message PackageRepositoryAuth {
  enum PackageRepositoryAuthType {
    PACKAGE_REPOSITORY_AUTH_TYPE_UNSPECIFIED = 0;
    PACKAGE_REPOSITORY_AUTH_TYPE_BASIC_AUTH = 1;              // uses UsernamePassword
    PACKAGE_REPOSITORY_AUTH_TYPE_TLS = 2;                     // uses TlsCertKey
    PACKAGE_REPOSITORY_AUTH_TYPE_BEARER = 3;                  // uses header
    PACKAGE_REPOSITORY_AUTH_TYPE_AUTHORIZATION_HEADER = 4;    // uses header
    PACKAGE_REPOSITORY_AUTH_TYPE_DOCKER_CONFIG_JSON = 5;      // uses DockerCredentials
    PACKAGE_REPOSITORY_AUTH_TYPE_SSH = 6;                     // uses SshCredentials
    PACKAGE_REPOSITORY_AUTH_TYPE_OPAQUE = 7;                  // uses OpaqueCredentials
  }
  PackageRepositoryAuthType type = 1;

  oneof package_repo_auth_one_of {
    // username and plain text password
    UsernamePassword username_password = 2;

    // certificate and key for TLS-based authentication
    TlsCertKey tls_cert_key = 3;

    // docker credentials
    DockerCredentials docker_creds = 4;

    // for Bearer Auth token value
    // for Custom Auth, complete value of "Authorization" header
    string header = 5;

    // a reference to an existing secret
    SecretKeyReference secret_ref = 6;

    // SSH credentials
    SshCredentials ssh_creds = 8;

    // opaque credentials
    OpaqueCredentials opaque_creds = 9;
  }

  // pass_credentials allows the credentials from the SecretRef to be passed
  // on to a host that does not match the host as defined in URL.
  // This flag controls whether or not it is allowed to passing credentials
  // with requests to other domains linked from the repository.
  // This may be needed if the host of the advertised chart URLs in the
  // index differs from the defined URL. Optional
  bool pass_credentials = 7;
}

// UsernamePassword
//
message UsernamePassword {
  // In clear text
  string username = 1;
  // In clear text
  string password = 2;
}

// TlsCertKey
//
message TlsCertKey {
  // certificate (identity). In clear text
  string cert = 1;
  // certificate key. In clear text
  string key = 2;
}

// DockerCredentials
//
message DockerCredentials {
  // server name
  string server = 1;
  // username.
  string username = 2;
  // password. In clear text
  string password = 3;
  // email address
  string email = 4;
}

// SshCredentials
//
message SshCredentials {
  // private key
  string private_key = 1;
  // known hosts.
  string known_hosts = 2;
}

// OpaqueCredentials
//
message OpaqueCredentials {
  // fields
  map<string,string> data = 1;
}

// SecretKeyReference
//
message SecretKeyReference {
  // The name of an existing secret in the same namespace as the object
  // that refers to it (e.g. PackageRepository), containing authentication
  // credentials for the said package repository.
  // - For HTTP/S basic auth the secret must be of type
  //   "kubernetes.io/basic-auth" or opaque and contain username and
  //   password fields
  // - For TLS the secret must be of type "kubernetes.io/tls" or opaque
  //   and contain a certFile and keyFile, and/or
  //   caCert fields.
  // - For Bearer or Custom Auth, the secret must be opaque, and
  //   the key must be provided
  // - For Docker Registry Credentials (OCI registries) the secret
  //   must of of type "kubernetes.io/dockerconfigjson"
  // For more details, refer to
  // https://kubernetes.io/docs/concepts/configuration/secret/
  string name = 1;

  // Optional. Must be provided when name refers to an opaque secret
  string key = 2;
}

// GetPackageRepositoryDetailRequest
//
// Request for GetPackageRepositoryDetail
message GetPackageRepositoryDetailRequest {
  PackageRepositoryReference package_repo_ref = 1;
}

// GetPackageRepositorySummariesRequest
//
// Request for PackageRepositorySummary
message GetPackageRepositorySummariesRequest {
  // The context (cluster/namespace) for the request.
  Context context = 1;
}

// UpdatePackageRepositoryRequest
//
// Request for UpdatePackageRepository
message UpdatePackageRepositoryRequest {
  // A reference uniquely identifying the package repository being updated.
  // The only required field
  PackageRepositoryReference package_repo_ref = 1;

  // URL identifying the package repository location.
  string url = 2;

  // A user-provided description.
  string description = 3;

  // The interval at which to check the upstream for updates (in time+unit)
  // Some plugins may, additionally, support other formats, for instance,
  // a cron expression.
  // e.g., "*/10 * * * *" will be equivalent to "10m"
  // Optional. Defaults to 10m if not specified
  string interval = 4;

  // TLS-specific parameters for connecting to a repository. Optional
  PackageRepositoryTlsConfig tls_config = 5;

  // authentication parameters for connecting to a repository. Optional
  PackageRepositoryAuth auth = 6;

  // Custom data added by the plugin
  // A plugin can define custom details for data which is not yet, or
  // never will be specified in the core AddPackageRepositoryRequest
  // fields. The use of an `Any` field means that each plugin can define
  // the structure of this message as required, while still satisfying the
  // core interface.
  // See https://developers.google.com/protocol-buffers/docs/proto3#any
  // Just for reference, some of the examples that have been chosen not to
  // be part of the core API but rather plugin-specific details are:
  //   direct-helm:
  //      - image pull secrets
  //      - list of oci repositories
  //      - filter rules
  //      - sync job pod template
  google.protobuf.Any custom_detail = 11;
}

// DeletePackageRepositoryRequest
//
// Request for DeletePackageRepository
message DeletePackageRepositoryRequest {
  PackageRepositoryReference package_repo_ref = 1;
}

// -- Start definitions of the response messages --

// PackageRepositoryReference
//
// A PackageRepositoryReference has the minimum information required to
// uniquely identify a package repository.
message PackageRepositoryReference {
  // The context (cluster/namespace) for the repository.
  Context context = 1;

  // The fully qualified identifier for the repository
  // (i.e. a unique name for the context).
  string identifier = 2;

  // The plugin used to interact with this available package.
  // This field should be omitted when the request is in the context of a
  // specific plugin.
  kubeappsapis.core.plugins.v1alpha1.Plugin plugin = 3;
}

// AddPackageRepositoryResponse
//
// Response for AddPackageRepositoryRequest
message AddPackageRepositoryResponse {
  // TODO: add example for API docs
  // option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
  //   example: '{"package_repo_ref": {}}'
  // };
  PackageRepositoryReference package_repo_ref = 1;
}

// PackageRepositoryStatus
//
// A PackageRepositoryStatus reports on the current status of the repository.
message PackageRepositoryStatus {
  // Ready
  //
  // An indication of whether the repository is ready or not
  bool ready = 1;

  // StatusReason
  //
  // Generic reasons why a package repository may be ready or not.
  // These should make sense across different packaging plugins.
  enum StatusReason {
    STATUS_REASON_UNSPECIFIED = 0;
    STATUS_REASON_SUCCESS = 1;
    STATUS_REASON_FAILED = 2;
    STATUS_REASON_PENDING = 3;
  }

  // Reason
  //
  // An enum indicating the reason for the current status.
  StatusReason reason = 2;

  // UserReason
  //
  // Optional text to return for user context, which may be plugin specific.
  string user_reason = 3;
}

// PackageRepositoryDetail
//
message PackageRepositoryDetail {
  // A reference uniquely identifying the package repository.
  PackageRepositoryReference package_repo_ref = 1;

  // A user-provided name for the package repository (e.g. bitnami)
  string name = 2;

  // A user-provided description.
  string description = 3;

  // Whether this repository is global or namespace-scoped.
  bool namespace_scoped = 4;

  // Package storage type
  string type = 5;

  // A URL identifying the package repository location.
  string url = 6;

  // The interval at which to check the upstream for updates (in time+unit)
  // Some plugins may, additionally, support other formats, for instance,
  // a cron expression.
  // e.g., "*/10 * * * *" will be equivalent to "10m"
  string interval = 7;

  // TLS-specific parameters for connecting to a repository.
  // If the cert authority was configured for this repository, then in the context
  // of GetPackageRepositoryDetail() operation, the PackageRepositoryTlsConfig will ALWAYS
  // contain an existing SecretKeyReference, rather that cert_authority field
  PackageRepositoryTlsConfig tls_config = 8;

  // authentication parameters for connecting to a repository.
  // If Basic Auth or TLS or Docker Creds Auth was configured for this repository,
  // then in the context of GetPackageRepositoryDetail() operation, the
  // PackageRepositoryAuth will ALWAYS contain an existing SecretKeyReference,
  // rather that string values that may have been used when package repository was created
  // field
  PackageRepositoryAuth auth = 9;

  // Custom data added by the plugin
  google.protobuf.Any custom_detail = 10;

  // current status of the repository which can include reconciliation
  // status, where relevant.
  PackageRepositoryStatus status = 11;
}

// GetPackageRepositoryDetailResponse
//
// Response for GetPackageRepositoryDetail
message GetPackageRepositoryDetailResponse {
  // package repository detail
  PackageRepositoryDetail detail = 1;
}

// PackageRepositorySummary
//
message PackageRepositorySummary {
  // A reference uniquely identifying the package repository.
  PackageRepositoryReference package_repo_ref = 1;

  // A user-provided name for the package repository (e.g. bitnami)
  string name = 2;

  // A user-provided description.
  string description = 3;

  // Whether this repository is global or namespace-scoped.
  bool namespace_scoped = 4;

  // Package storage type
  string type = 5;

  // URL identifying the package repository location.
  string url = 6;

  // current status of the repository which can include reconciliation
  // status, where relevant.
  PackageRepositoryStatus status = 7;

  // existence of any authentication parameters for connecting to a repository.
  bool requires_auth = 8;
}

// GetPackageRepositorySummariesResponse
//
// Response for GetPackageRepositorySummaries
message GetPackageRepositorySummariesResponse {
  // List of PackageRepositorySummary
  repeated PackageRepositorySummary package_repository_summaries = 1;
}

// UpdatePackageRepositoryResponse
//
// Response for UpdatePackageRepository
message UpdatePackageRepositoryResponse {
  PackageRepositoryReference package_repo_ref = 1;
}

// DeletePackageRepositoryResponse
//
// Response for DeletePackageRepository
message DeletePackageRepositoryResponse {
  // For future extensibility only.
 }

 message GetPackageRepositoryPermissionsRequest {
   // The context (cluster/namespace) for the request
   Context context = 1;
 }

 message PackageRepositoriesPermissions {
   kubeappsapis.core.plugins.v1alpha1.Plugin plugin = 1;
   // Permissions at the global namespace (if any)
   map<string, bool> global = 2;
   // Permissions for the namespace
   map<string, bool> namespace = 3;
 }

 message GetPackageRepositoryPermissionsResponse {
   repeated PackageRepositoriesPermissions permissions = 1;
 }