Skip to main content

Core concepts

Kube-DC uses Organizations and Projects to connect identity, authorization, networking, resource governance, and billing to the workloads you deploy. This page explains that model. It also explains the choice you make before each deployment: run the workload in your Project, or in a Managed Cluster. Those two ideas cover most of what you need to use the platform.

The resource model​

Kube-DC cloud resource modelAn Organization contains Projects. A Project maps to a backing namespace and can contain applications and namespaced Kubernetes resources, virtual machines, networking, storage, managed services, and Managed Clusters with a separate Kubernetes API.GOVERNANCEOrganizationidentity · membershipbilling · shared quotaProjectworking boundary · backing namespacePROJECT CAPABILITIESApplicationsnamespacedresourcesVirtual machinesKubeVirtPlatform servicesnetwork · storagemanaged servicesManaged Clustersseparate API
An Organization supplies the identity, membership, billing, and shared-quota boundary; each Project is a separate working boundary containing namespaced workloads and optional Managed Clusters.

Organization: identity and billing scope​

An Organization represents a customer account, a company, or a team. It owns:

  • An organization-scoped identity realm. Single sign-on runs on Keycloak and accepts optional external identity providers.
  • Membership and role assignments. Invite a user once, then grant per-Project roles.
  • Projects.
  • Billing and aggregated resource usage.

The Organization is the account boundary, not the workload boundary. Workload access, networking, and resource limits apply at Project scope.

Project: the working boundary​

A Project is a governed Kubernetes application environment on the shared platform cluster. Teams commonly create one Project per environment, such as production, staging, and dev. One Project per application or per customer also works.

Each Project provides:

  • A dedicated backing namespace named {organization}-{project}
  • Project-scoped RBAC with the Admin, Developer, Project Manager, and User roles, plus any custom roles you define
  • A private network (VPC) with platform-managed traffic controls
  • An optional quota for CPU, memory, storage, and other resources
  • A kubeconfig for direct Kubernetes API access

A Project is not a tenant Kubernetes cluster. Its users share the platform API server and the platform-operated controllers. They work inside the backing namespace, the RBAC, the network, and the security boundaries assigned to the Project. In exchange, the Project is ready the moment it exists. There is no cluster to provision or operate. See Projects.

Resources that belong to a Project​

  • Deployments, StatefulSets, DaemonSets, Pods, and Jobs
  • Services, Ingresses, and Gateway API routes
  • Persistent volume claims and S3-compatible object buckets
  • Linux and Windows virtual machines
  • External IPs, floating IPs, and load balancers
  • Managed services from the provider catalog
  • Certificates, secrets, KMS keys, and database credential policies
  • Managed Clusters and platform-managed protection services

Choose a deployment mode​

Kube-DC gives you two ways to run Kubernetes workloads. Choose one for each workload before you deploy it. The following table compares them:

PropertyProject (default)Managed Cluster
Control boundaryOne governed backing namespace on the shared platform clusterA tenant-controlled Kubernetes control plane
Best forApplications, services, storage, jobs, and VMs that use supported namespaced APIsOperators, platform stacks, multiple namespaces, cluster-level customization
AccessProject kubeconfig, available as soon as the Project existsCluster kubeconfig, available after the control plane and workers are ready
ExtensibilityPlatform-installed APIs and supported namespaced resourcesFull Kubernetes: CRDs, webhooks, operators, cluster RBAC
You operateNothing below your workloadsWorker pool sizing and upgrade timing
Selection rule

Choose a Project for application deployments and VMs whose manifests use supported namespaced APIs and unprivileged pods.

Choose a Managed Cluster when the software installs operators or CRDs, creates cluster-scoped resources, spans multiple namespaces, or needs privileged or host-level access.

The two modes are separate deployment targets. To move a workload from a Project to a Managed Cluster, you redeploy it against a new API endpoint. Helm release state, persistent data, IP addresses, and DNS endpoints each need an explicit migration plan. Make the choice before you deploy.

How isolation works​

Isolation in Kube-DC is layered, and each layer has a precise scope. The following table lists the layers:

LayerScopeMechanism
IdentityOrganizationOrganization-scoped SSO realm; Projects grant roles within it
AuthorizationProjectDedicated backing namespace with per-role RBAC
NetworkProjectA VPC per Project on the platform SDN
CapacityProject and OrganizationOptional per-Project quotas within your plan
BillingOrganizationOne plan and one invoice across all Projects

Project networks​

  • Platform-managed VPC controls block cross-Project routing by default. A VM or pod in production cannot reach one in staging until you expose it, even inside the same Organization.
  • Separate Projects can reuse the same internal CIDR ranges without conflict, in the same way as VPCs at a public cloud.
  • External reachability is explicit. Attach external IPs, floating IPs, or LoadBalancer Services to bring traffic in. Egress leaves through your Project's gateway.

The platform operates the traffic controls on the shared cluster. Tenants do not author NetworkPolicy resources in Projects.

Kubernetes-native APIs​

Kube-DC represents its cloud services as platform-installed Kubernetes APIs. You create instances of those resources in your Project, such as a database, a certificate, or a public IP. You do not create the CRD definitions themselves.

You can manage a Project with:

  • kubectl and the Kubernetes API
  • Compatible Helm charts
  • Terraform, through the Kubernetes provider
  • The web console and the kube-dc CLI
  • An externally operated Argo CD or Flux, pointed at the Project kubeconfig
  • AI coding assistants, through agent skills

A Helm chart is compatible when all four of these are true:

  1. It uses Kubernetes APIs that the Project supports.
  2. It stays inside the Project's backing namespace.
  3. It needs only verbs granted to the installing user.
  4. It complies with the Project pod-security policy.

Projects do not support charts that create CRDs, cluster-scoped RBAC, admission webhooks, StorageClasses, NetworkPolicies, CronJobs, or workloads that need privileged or host access. Use a Managed Cluster for those. For the full boundary, and for how to check a chart before you install it, see Projects.

Project backing namespaces block kubectl exec and kubectl attach by design. Use kubectl logs, and run administrative tasks as Jobs. Project administrators can define custom namespaced Roles within their own authority. A namespaced Role can never grant cluster-scoped resources, and admission policy enforces the exec restriction even for custom roles.

Next steps​