> For the complete documentation index, see [llms.txt](https://bluebricks.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluebricks.co/docs/getting-started/connect-your-cloud/kubernetes-integration.md). # Kubernetes Integration Kubernetes integration extends the [context layer](/docs/getting-started/building-blocks.md#the-context-layer) beyond cloud APIs and static Helm chart templates. After you connect AWS, Azure, or GCP with discovery enabled, Bluebricks finds managed clusters in those accounts, polls their APIs, and indexes live workload state so the [agent](/docs/agent/agents-overview.md) can answer questions about what is actually running. You do not connect Kubernetes as a separate cloud provider in the app today. Cluster visibility uses the same discovery [collection](/docs/orchestration/collections.md) and cloud account as your AWS, GCP, or Azure connection. For cloud connection basics, see [Connect your Cloud](/docs/getting-started/connect-your-cloud.md). {% hint style="success" %} **Ask the agent.** Query live cluster state through natural conversation after discovery completes. See [Agent overview](/docs/agent/agents-overview.md). {% endhint %} ## What this integration includes | Capability | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------- | | **Cluster detection** | Managed clusters (EKS, GKE, AKS) are discovered during cloud inventory scans | | **Live object indexing** | Workloads such as Deployments, Jobs, Pods, Services, Ingresses, and ConfigMaps are synced into the context layer | | **Helm correlation** | Live objects link to Helm releases and chart templates when standard Helm labels are present | | **Cloud linkage** | Objects connect to the underlying cluster and load balancers already modeled as cloud resources | This is distinct from [Helm orchestration](/docs/orchestration/packages/artifacts-overview/helm.md) (deploying charts through environments) and from the [self-hosted runner](/docs/organization-and-security/bluebricks-self-hosted-runner/what-is-a-self-hosted-cloud.md) (running the Bluebricks Deployments Controller inside your cluster). ## How it works ```mermaid flowchart LR A[Cloud connection with discovery] --> B[Cloud discovery scan] B --> C[Discover EKS, GKE, and AKS] C --> D[Sync live workload state] D --> E[Context layer] E --> F[Agent] ``` 1. Connect a cloud account with **discovery** on a [collection](/docs/orchestration/collections.md), using [AWS](/docs/getting-started/connect-your-cloud/how-to-connect-aws.md), [GCP](/docs/getting-started/connect-your-cloud/how-to-connect-gcp.md), or [Azure](/docs/getting-started/connect-your-cloud/how-to-connect-azure.md). 2. Bluebricks runs a read-only cloud scan and discovers managed Kubernetes clusters in that account or project. 3. For each cluster, Bluebricks syncs live workload state from the Kubernetes API using credentials from your cloud connection. No agent pod runs inside your cluster. 4. Synced objects enter the [context layer](/docs/getting-started/building-blocks.md#the-context-layer) and link to Helm releases, infrastructure code, and related cloud resources. You query those relationships through the [agent](/docs/agent/agents-overview.md), not through the Cloud Graph canvas. ## Supported managed clusters | Cloud provider | Supported clusters | | -------------- | --------------------------------------------------------- | | **AWS** | Amazon EKS | | **GCP** | Google Kubernetes Engine (GKE) | | **Azure** | Azure Kubernetes Service (AKS) and Arc-connected clusters | Clusters that never appear in cloud discovery for a connected account are outside this integration. That includes on-premises kubeconfig-only clusters and local development clusters not registered with EKS, GKE, or AKS. Use the [self-hosted runner](/docs/organization-and-security/bluebricks-self-hosted-runner/what-is-a-self-hosted-cloud.md) when you need orchestration against a cluster Bluebricks does not discover from a public cloud API. ## Chart intent vs live cluster state The context layer has long reflected Kubernetes **intent** from Helm chart sources in your connected repositories. Kubernetes integration adds **live state**: | | Helm templates in code | Live Kubernetes objects | | -------------------- | ---------------------------------- | ---------------------------------------------- | | **Source** | Chart files in connected Git repos | Kubernetes API on discovered clusters | | **Represents** | What the chart declares | What is running now (status, failures, labels) | | **Example question** | "What does this chart deploy?" | "Why did this Job fail in production?" | The agent can relate a failed Job to its Helm release, the blueprint or Terraform that owns the cluster, and cloud resources such as load balancers fronting an Ingress. ## Prerequisites 1. A [collection](/docs/orchestration/collections.md) linked to AWS, GCP, or Azure with **discovery** enabled on the cloud connection 2. At least one managed Kubernetes cluster in that account or project that cloud discovery can list 3. Discovery credentials that can authenticate to the cluster API through the cloud provider For discovery vs orchestration permission types, see [Connect your Cloud](/docs/getting-started/connect-your-cloud.md#permissions). ## Required permissions Kubernetes integration reuses **discovery** permissions on your cloud connection; it does not add a separate permission type in the app. Your discovery role or service account must be able to: * List and describe managed Kubernetes clusters in the cloud API (for example EKS, GKE, or AKS control planes) * Obtain short-lived credentials to call the Kubernetes API for those clusters through the provider's supported mechanism Provider-specific roles: | Provider | Additional role for live Kubernetes indexing | | --------------- | ------------------------------------------------------------------------------------- | | **AWS (EKS)** | EKS access entry with `AmazonEKSViewPolicy` on the discovery IAM role | | **GCP (GKE)** | `roles/container.viewer` (Kubernetes Engine Viewer) on the Bluebricks service account | | **Azure (AKS)** | Azure Kubernetes Service RBAC Reader on the service principal | For GCP, grant Kubernetes Engine Viewer in addition to the three base discovery roles documented in [Connecting to GCP](/docs/getting-started/connect-your-cloud/how-to-connect-gcp.md#grant-gke-permissions). If cluster objects never appear after a successful cloud connection, verify discovery can see the cluster in the cloud console and that the discovery role has not been scoped down to exclude Kubernetes services. ## Network access and IP whitelisting Kubernetes indexing calls your cluster API from the Bluebricks platform over HTTPS (port 443). Traffic is **outbound from Bluebricks to your API server endpoint**, not from a pod inside your cluster. If the control plane is private or restricted by IP allowlists, allow the [Bluebricks egress IP ranges](/docs/organization-and-security/netwrok-access-requirements.md#ip-whitelist) on the cluster API before live object sync can succeed. Cloud discovery may still list the cluster even when API polling is blocked. Apply those ranges using your provider's control plane access settings: | Provider | Typical control | | --------------- | ---------------------------------------------------------------------------------------------------------------------- | | **AWS (EKS)** | Public endpoint access and security groups or EKS public endpoint CIDR restrictions on the cluster API | | **GCP (GKE)** | [Authorized networks](https://cloud.google.com/kubernetes-engine/docs/how-to/authorized-networks) on the control plane | | **Azure (AKS)** | [Authorized IP ranges](https://learn.microsoft.com/en-us/azure/aks/api-server-authorized-ip-ranges) on the API server | {% hint style="warning" %} **Private-only API servers**\ If the Kubernetes API is reachable only inside a VPC or private link with no path from the public internet, Bluebricks cannot poll it with the current managed-cluster integration. You will still see the cluster in cloud inventory, but live workload indexing will not run until API access from the whitelisted Bluebricks IPs is possible. For private endpoints or other restricted topologies, [contact support](https://www.bluebricks.co/support) to discuss a custom connection. {% endhint %} ## Verify integration is working After discovery completes on the collection: 1. Open the [agent](/docs/agent/agents-overview.md) and ask a cluster-scoped question, for example: "List failed Jobs in the production EKS cluster" or "Which Ingress fronts this load balancer?" 2. Confirm the agent returns answers grounded in live status (pod phases, Job conditions, Ingress hostnames), not only chart YAML That is the supported way to validate live workload indexing. Indexed Kubernetes objects feed the context layer behind the agent; there is no separate in-app graph for browsing Pods, Jobs, or Ingress relationships. The [Cloud Graph](/docs/orchestration/cloud-graph.md) is a separate surface. It visualizes collections, environments, and **cloud** resources from discovery (managed vs. unmanaged, codification). You may see a managed cluster there as a cloud resource (for example an EKS cluster in inventory), but the Cloud Graph does not chart live Pods, Jobs, Ingresses, or Helm-to-workload relationships. Use the agent for that. Indexing runs on a schedule with cloud discovery. New clusters may take until the next discovery cycle to appear. ## Limitations These constraints match what [Connect your Cloud](/docs/getting-started/connect-your-cloud.md#supported-cloud-providers) supports today. They apply to **live workload indexing** for the agent and context layer, not to [Helm deployments](/docs/orchestration/packages/artifacts-overview/helm.md) or the [self-hosted runner](/docs/organization-and-security/bluebricks-self-hosted-runner/what-is-a-self-hosted-cloud.md). | Limitation | What this means for you | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **No Kubernetes-only cloud connection** | The app connects **AWS**, **GCP**, or **Azure** accounts only. There is no separate flow to attach a cluster by kubeconfig or API URL alone. Enable discovery on one of those cloud connections first. | | **Managed clusters from cloud inventory** | Live indexing runs for **EKS**, **GKE**, and **AKS** (including Arc-connected clusters) that cloud discovery lists in your account or project. If the cluster does not show up in the provider console as a managed cluster resource, Bluebricks cannot index its workloads through this feature. | | **No in-cluster discovery software** | Bluebricks polls the Kubernetes API from its platform. You do not install a Bluebricks DaemonSet, operator, or agent in the cluster for this integration. | | **Built-in resource kinds only** | Standard types such as Deployments, Jobs, Pods, Services, Ingresses, ConfigMaps, StatefulSets, and CronJobs are synced. **Custom resources (CRDs)** are not indexed. | | **Agent, not Cloud Graph, for live workloads** | The [Cloud Graph](/docs/orchestration/cloud-graph.md) shows cloud inventory and orchestration structure, not an interactive graph of in-cluster objects. Live Kubernetes questions and cross-links (Job to Helm release, Ingress to load balancer) are available through the agent. | ## Related documentation * [Connect your Cloud](/docs/getting-started/connect-your-cloud.md): cloud providers and discovery vs orchestration permissions * [Connecting to AWS](/docs/getting-started/connect-your-cloud/how-to-connect-aws.md), [Connecting to GCP](/docs/getting-started/connect-your-cloud/how-to-connect-gcp.md), [Connecting to Azure](/docs/getting-started/connect-your-cloud/how-to-connect-azure.md) * [Agent overview](/docs/agent/agents-overview.md) * [Cloud Graph](/docs/orchestration/cloud-graph.md): cloud resource inventory and environments (not live in-cluster workload graph) * [Helm artifacts](/docs/orchestration/packages/artifacts-overview/helm.md): deploying to connected clusters through orchestration * [Network access requirements](/docs/organization-and-security/netwrok-access-requirements.md): domain and IP whitelist for Bluebricks services * [Self-hosted runner](/docs/organization-and-security/bluebricks-self-hosted-runner/what-is-a-self-hosted-cloud.md): running deployments inside your own cluster --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://bluebricks.co/docs/getting-started/connect-your-cloud/kubernetes-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.