Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/cobaltcore-dev/metal-credential-sync

A Kubernetes Operator that synchronizes BMC (Baseboard Management Controller) credentials from the metal-operator’s BMCSecret resources to external secret backends like HashiCorp Vault or OpenBao.
https://github.com/cobaltcore-dev/metal-credential-sync

go kubernetes operator

Last synced: 3 days ago
JSON representation

A Kubernetes Operator that synchronizes BMC (Baseboard Management Controller) credentials from the metal-operator’s BMCSecret resources to external secret backends like HashiCorp Vault or OpenBao.

Awesome Lists containing this project

README 

          
[![REUSE status](https://api.reuse.software/badge/github.com/cobaltcore-dev/metal-credential-sync)](https://api.reuse.software/info/github.com/cobaltcore-dev/metal-credential-sync)



# metal-credential-sync



## About this project



A Kubernetes Operator that synchronizes BMC (Baseboard Management Controller) credentials from the metal-operator’s BMCSecret resources to external secret backends like HashiCorp Vault or OpenBao.



## Overview



Metal Credential Sync watches BMCSecret resources from the [metal-operator](https://github.com/ironcore-dev/metal-operator), discovers associated BMC infrastructure, and maintains synchronized copies in configurable backend systems using logical hierarchical paths (region/hostname/username).



## Features



- **Automatic Synchronization**: Watches BMCSecret resources and syncs credentials to external backends

- **Selective Sync**: Optional label-based filtering to control which BMCSecrets are synced

- **Multi-BMC Support**: Creates separate backend entries for each BMC that shares credentials

- **Flexible Path Construction**: Configurable path templates using region, hostname, and username

- **Pluggable Backend Architecture**: Interface-based design supporting multiple backends

- **HashiCorp Vault Support**: Full support for Vault KV v1 and v2 engines

- **Multiple Auth Methods**: Kubernetes service account auth, token auth, and AppRole (future)

- **Automatic Cleanup**: Removes backend secrets when BMCSecrets are deleted

- **Configuration Options**: CRD-based or environment variable configuration

- **Runtime Config Reload**: Automatically detects and applies SecretBackendConfig changes

- **Sync Status Tracking**: Dedicated CRD tracks synchronization state per BMCSecret



## Architecture



```

BMCSecret (metal-operator)

    └─> Metal Credential Sync watches

        └─> Discovers BMC resources

            └─> Extracts region, hostname, username

                └─> Builds Vault path: bmc///

                    └─> Syncs credentials to Vault

```



## Installation



### Prerequisites



- Kubernetes cluster (v1.30+)

- [metal-operator](https://github.com/ironcore-dev/metal-operator) v0.3.0+ installed

- HashiCorp Vault server (v1.12.0+) with KV secrets engine enabled

- Go 1.25.6+ (for building from source)



### Install CRDs



```bash

make install

```



### Deploy Operator



```bash

# Build and push image

make docker-build docker-push IMG=/metal-credential-sync:latest



# Deploy to cluster

make deploy IMG=/metal-credential-sync:latest

```



## Configuration



### Option 1: SecretBackendConfig CRD (Recommended)



Create a `SecretBackendConfig` resource:



```yaml

apiVersion: config.metal.ironcore.dev/v1alpha1

kind: SecretBackendConfig

metadata:

  name: default-backend-config

spec:

  backend: vault

  vaultConfig:

    address: "https://vault.example.com:8200"

    authMethod: kubernetes

    kubernetesAuth:

      role: metal-credential-sync

      path: kubernetes

    mountPath: secret

    tlsConfig:

      skipVerify: false

  pathTemplate: "bmc/{{.Region}}/{{.Hostname}}/{{.Username}}"

  regionLabelKey: "region"

  # Optional: Only sync BMCSecrets with this label

  syncLabel: "metal-credential-sync.metal.ironcore.dev/sync"

```



Apply the configuration:



```bash

kubectl apply -f config/samples/config_v1alpha1_secretbackendconfig.yaml

```



**Runtime Configuration Changes**: The operator watches the `SecretBackendConfig` resource and automatically detects changes. When you update the configuration (e.g., change `regionLabelKey` or `pathTemplate`), the operator invalidates its cache and applies the new configuration on the next reconciliation cycle (within 5 minutes). See [MIGRATION.md](./MIGRATION.md) for details on handling configuration changes and migrating secrets.



### Selective Sync with Labels



If you configure a `syncLabel`, only BMCSecrets with that label will be synced:



```yaml

spec:

  syncLabel: "metal-credential-sync.metal.ironcore.dev/sync"

```



Then label BMCSecrets you want to sync:



```yaml

apiVersion: metal.ironcore.dev/v1alpha1

kind: BMCSecret

metadata:

  name: admin-creds

  labels:

    metal-credential-sync.metal.ironcore.dev/sync: "true"

data:

  username: YWRtaW4=

  password: c2VjcmV0MTIz

```



If `syncLabel` is not configured or empty, all BMCSecrets will be synced.



### Option 2: Environment Variables (Fallback)



If no `SecretBackendConfig` is found, the operator falls back to environment variables:



```yaml

env:

- name: SECRET_BACKEND_TYPE

  value: vault

- name: VAULT_ADDR

  value: https://vault.example.com:8200

- name: VAULT_AUTH_METHOD

  value: kubernetes

- name: VAULT_ROLE

  value: metal-credential-sync

- name: VAULT_MOUNT_PATH

  value: secret

- name: PATH_TEMPLATE

  value: "bmc/{{.Region}}/{{.Hostname}}/{{.Username}}"

- name: REGION_LABEL_KEY

  value: region

- name: SYNC_LABEL

  value: "metal-credential-sync.metal.ironcore.dev/sync"

```



## Vault Setup



### Enable KV v2 Engine



```bash

vault secrets enable -version=2 -path=secret kv

```



### Create Policy



```bash

vault policy write bmc-operator - < -o yaml

```



### Vault connection issues



Test connectivity from operator pod:



```bash

kubectl exec -n metal-credential-sync-system \

  deployment/metal-credential-sync-controller-manager -- \

  curl -k https://vault.example.com:8200/v1/sys/health

```



## Roadmap



- [ ] OpenBao backend implementation

- [ ] AppRole authentication method

- [ ] Status conditions on BMCSecret

- [ ] Metrics and Prometheus integration

- [ ] Webhook validation for SecretBackendConfig

- [ ] Password hash comparison (instead of plaintext)

- [ ] Token renewal for long-running operations

- [ ] Integration tests with testcontainers

- [ ] E2E tests with real Vault instance



## Support, Feedback, Contributing



This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cobaltcore-dev/metal-credential-sync/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).



## Related Projects



- [metal-operator](https://github.com/ironcore-dev/metal-operator) - Kubernetes operator for bare metal management

- [HashiCorp Vault](https://www.vaultproject.io/) - Secrets management solution

- [OpenBao](https://openbao.org/) - Open source Vault fork



## Security / Disclosure

If you find any bug that may be a security problem, please follow our instructions at [in our security policy](https://github.com/cobaltcore-dev/metal-credential-sync/security/policy) on how to report it. Please do not create GitHub issues for security-related doubts or problems.



## Code of Conduct



We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/SAP/.github/blob/main/CODE_OF_CONDUCT.md) at all times.



## Licensing



Copyright 2026 SAP SE or an SAP affiliate company and metal-credential-sync contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/cobaltcore-dev/metal-credential-sync).





  Bundesministerium für Wirtschaft und Energie (BMWE)-EU funding logo