{"id":13668697,"url":"https://github.com/spiffe/spire-controller-manager","last_synced_at":"2025-04-05T16:03:19.090Z","repository":{"id":39136330,"uuid":"425999890","full_name":"spiffe/spire-controller-manager","owner":"spiffe","description":"Kubernetes controller manager that reconciles workload registration and federation relationships.","archived":false,"fork":false,"pushed_at":"2025-03-25T15:55:39.000Z","size":901,"stargazers_count":61,"open_issues_count":26,"forks_count":42,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-29T08:33:43.429Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spiffe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-08T21:30:25.000Z","updated_at":"2025-03-26T08:31:00.000Z","dependencies_parsed_at":"2023-10-02T17:17:19.238Z","dependency_job_id":"a112c787-b848-4308-8f9b-c946f227f931","html_url":"https://github.com/spiffe/spire-controller-manager","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiffe%2Fspire-controller-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiffe%2Fspire-controller-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiffe%2Fspire-controller-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiffe%2Fspire-controller-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spiffe","download_url":"https://codeload.github.com/spiffe/spire-controller-manager/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247361593,"owners_count":20926641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T08:00:47.408Z","updated_at":"2025-04-05T16:03:19.011Z","avatar_url":"https://github.com/spiffe.png","language":"Go","funding_links":[],"categories":["Utils"],"sub_categories":["SDK"],"readme":"# SPIRE Controller Manager\n\n[![Build Status](https://github.com/spiffe/spire-controller-manager/actions/workflows/nightly_build.yaml/badge.svg)](https://github.com/spiffe/spire-controller-manager/actions/workflows/nightly_build.yaml)\n[![Pre-Production Phase](https://github.com/spiffe/spiffe/blob/main/.img/maturity/pre-prod.svg)](https://github.com/spiffe/spiffe/blob/main/MATURITY.md#pre-production)\n\n\nA [Kubernetes Controller](https://kubernetes.io/docs/concepts/architecture/controller/)\nmanager which facilitates the registration of workloads and establishment\nof federation relationships.\n\n## How it Works\n\n### Custom Resources\n\n#### ClusterSPIFFEID\n\nThe [ClusterSPIFFEID](docs/clusterspiffeid-crd.md) resource is a cluster scoped\nCRD that describes the shape of the identity that is applied to workloads, as\nwell as selectors that describe which workloads the identity applies to.\n\n#### ClusterFederatedTrustDomain\n\nThe [ClusterFederatedTrustDomain](docs/clusterfederatedtrustdomain-crd.md)\nresource is a cluster scoped CRD that describes a federation relationship for\nthe cluster.\n\n### ClusterStaticEntry\n\nThe [ClusterStaticEntry](docs/clusterstaticentry-crd.md) resource is a cluster\nscoped CRD that describes a static SPIRE registration entry. It is typically\nused for registering workloads that do not run in the Kubernetes cluster but\notherwise need to be part of the trust domain (e.g. downstream nested SPIRE\nservers).\n\n### Reconciliation\n\n#### Workload Registration\n\nTo facilitate workload registration, the SPIRE Controller manager registers\ncontrollers against the following resources:\n\n- [Pods](https://kubernetes.io/docs/concepts/workloads/pods/)\n- [ClusterSPIFFEID](docs/clusterspiffeid-crd.md)\n- [ClusterStaticEntry](docs/clusterstaticentry-crd.md)\n\nWhen changes are detected on these resources, a workload reconciliation process\nis triggered. This process determines which SPIRE entries should exist based on\nthe existing Pods and ClusterSPIFFEID resources which apply to those pods, as\nwell as static entries declared via ClusterStaticEntry resources. The\nreconciliation process creates, updates, and deletes entries on SPIRE server as\nappropriate to match the declared state.\n\n#### Federation\n\nTo facilitate federation, the SPIRE Controller manager registers controllers\nagainst the following resources:\n\n- [ClusterFederatedTrustDomain](docs/clusterfederatedtrustdomain-crd.md)\n\nWhen changes are detected on these resources, a federation relationship\nreconciliation process is triggered. This process determines which SPIRE\nfederation relationships should exist based on the existing\nClusterFederatedTrustDomain resources. It creates, updates, and deletes\nfederation relationships as appropriate to match the declared state.\n\n## Deployment\n\nThe SPIRE Controller Manager is designed to be deployed in the same pod as the\nSPIRE Server. It communicates with the SPIRE Server API using a private Unix\nDomain Socket within a shared volume. It requires [configuration](docs/spire-controller-manager-config.md)\nfor the environment where it is being deployed.\n\nThe [demo](demo) includes [sample configuration](demo/config/cluster1) for\ndeploying the SPIRE Controller Manager, SPIRE, and the SPIFFE CSI driver,\nincluding requisite RBAC and Webhook configuration.\n\n### Upgrading\n\nThe SPIRE Controller Manager must have the correct set of [Custom Resources](#custom-resources) \nand the `manager-role` that corresponds to the version to be installed.\n\nBefore upgrading, please install custom resources from [config/crd](/config/crd) and \nverify that [manager-role](/config/rbac/role.yaml) is up-to-date.\n\n## Compatibility\n\nThe SPIRE APIs used by the SPIRE Controller Manager are generally stable and\nsupported since at least SPIRE v1.0. However, the API has gained support for\nadditional entry fields beyond what was supported in SPIRE v1.0. Notably, these\ninclude the `jwt_svid_ttl`, `hint` and the `store_svid` fields. The\nClusterStaticEntry CRD allows these fields to be set, however, a SPIRE server\nthat does not support these fields will not retain them. This means if these\nfields are set on a ClusterStaticEntry with an older version of SPIRE, the\nSPIRE Controller Manager will continously try to reconcile SPIRE server. In\norder to use these fields, you must be on a version of SPIRE Server which\nsupports them.\n\nAt the moment, SPIRE Controller Manager will silently try and reconcile these\nfields over and over. Future updates may cause the SPIRE Controller Manager\nto fail when an unsupporting SPIRE Server is encounted while these fields\nare set.\n\nThe `hint` field is supported as of SPIRE 1.6.3.\n\nThe `jwt_svid_ttl` field is supported as of SPIRE 1.5.0.\n\nThe `store_svid` field is supported as of SPIRE 1.1.0.\n\n## Demo\n\n[Link](demo)\n\n## Troubleshooting\n\n### Workloads\n\n#### Workload Not Registered\n\n##### ClusterSPIFFEID Not Defined\n\nDefine a ClusterSPIFFEID that applies to the workload pod.\n\n##### Workload Pod Excluded by ClusterSPIFFEID PodSelector or NamespaceSelector\n\nAdjust the ClusterSPIFFEID selectors.\n\n##### Failed to Render Templates Against Workload Pod or Node\n\nCheck the ClusterSPIFFEID status for entry render failures. Check logs to\ndetermine why the rendering failed.\n\n##### Failed to Register with SPIRE Server\n\nCheck logs for API failures talking to SPIRE Server.\n\n### Federation\n\n#### Federation Relationship Missing\n\n##### ClusterFederatedTrustDomain Not Defined\n\nDefine a ClusterFederatedTrustDomain for the target trust domain.\n\n##### ClusterFederatedTrustDomain TrustDomain Conflict\n\nEnsure each ClusterFederatedTrustDomain resource has a unique trust domain. The\ncontroller will only ignore all but the oldest ClusterFederatedTrustDomain\nresource with a conflicting trust domain. \n\n#### Workload Not Federated With Trust Domain\n\nCheck the ClusterSPIFFEID for the workload. The federatesWith field must\ninclude the federated trust domain.\n\n## Security\n\n### Reporting a Vulnerability\n\nVulnerabilities can be reported by sending an email to security@spiffe.io. A\nconfirmation email will be sent to acknowledge the report within 72 hours. A\nsecond acknowledgement will be sent within 7 days when the vulnerability has\nbeen positively or negatively confirmed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspiffe%2Fspire-controller-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspiffe%2Fspire-controller-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspiffe%2Fspire-controller-manager/lists"}