Terraform Provider pro MazeVault¶

MazeVault Terraform Provider umožňuje spravovat celou infrastrukturu MazeVault jako kód — projekty, tajné hodnoty, certifikáty, rotace, řízení přístupu a integrace s externími systémy.

Registry: registry.terraform.io/providers/MazeVault/mazevault
Vyžaduje: Terraform ≥ 1.11, MazeVault ≥ 1.0.48
Kompletní reference atributů: Terraform Registry dokumentace

Instalace¶

terraform {
  required_version = ">= 1.11"
  required_providers {
    mazevault = {
      source  = "MazeVault/mazevault"
      version = "~> 1.0"
    }
    random = {
      source = "hashicorp/random"
    }
  }
}

Konfigurace providera¶

provider "mazevault" {
  server_url = "https://vault.example.com"
  api_token  = var.mazevault_token   # nebo env: MAZEVAULT_API_TOKEN
}

Argument	Env proměnná	Popis
`server_url`	`MAZEVAULT_SERVER_URL`	Základní URL MazeVault serveru
`api_token`	`MAZEVAULT_API_TOKEN`	API token (doporučeno)
`client_id`	`MAZEVAULT_CLIENT_ID`	OAuth2 client ID servisního účtu
`client_secret`	`MAZEVAULT_CLIENT_SECRET`	OAuth2 client secret servisního účtu
`timeout`	—	Timeout požadavků, např. `30s` (výchozí)
`skip_tls_verify`	—	Vypnutí TLS kontroly — pouze pro vývoj

Zacházení s přihlašovacími údaji

Nikdy nevkládejte přihlašovací údaje přímo do .tf souborů. Používejte proměnné prostředí nebo úložiště tajných hodnot v CI/CD. Nikdy necommitujte .tfvars soubory s tokeny nebo hesly.

Autentizace¶

API Token (doporučeno)¶

export MAZEVAULT_SERVER_URL="https://vault.example.com"
export MAZEVAULT_API_TOKEN="mv_pat_xxxxx"
terraform plan

Tokeny vytvoříte v Admin → API Tokeny nebo zdrojem mazevault_api_token.

Servisní účet (CI/CD pipeline)¶

provider "mazevault" {
  server_url    = var.server_url
  client_id     = var.client_id
  client_secret = var.client_secret
}

Příklad: nastavení externí CA¶

Použijte mazevault_ca_account.settings pro netajnou konfiguraci CA providera, kterou MazeVault potřebuje znovu použít při synchronizaci produktů, pollingu obnov a DCV kontrolách. API klíče, hesla a EAB HMAC klíče patří do dedikovaných citlivých atributů, ne do settings. provider_type nastavte na dokumentovanou hodnotu malými písmeny, například digicert, letsencrypt nebo acme; smíšená velikost písmen a okolní mezery jsou odmítnuty ještě před odesláním požadavku do MazeVaultu.

resource "mazevault_ca_account" "digicert" {
  organization_id = mazevault_organization.acme.id
  name            = "DigiCert Production"
  provider_type   = "digicert"
  api_key         = var.digicert_api_key
  base_url        = "https://www.digicert.com"

  settings = {
    organization_id       = var.digicert_organization_id
    server_platform_id    = "45"
    dcv_method            = "dns_txt"
    certificate_dcv_scope = "base_domain"
  }
}

Příklad: Správa tajných hodnot se synchronizací do Azure Key Vault¶

Vytvoří projekt, uloží databázové heslo a synchronizuje ho do Azure Key Vault s automatickou 30denní rotací.

resource "mazevault_organization" "acme" {
  name = "Acme Corp"
}

resource "mazevault_project" "backend" {
  organization_id = mazevault_organization.acme.id
  name            = "Backend Services"
  type            = "secret"
}

resource "mazevault_integration" "azure_kv" {
  project_id  = mazevault_project.backend.id
  name        = "Produkční Key Vault"
  type        = "azure_key_vault"
  environment = "production"
  config = {
    vault_url            = var.keyvault_url
    use_managed_identity = "true"
  }
}

ephemeral "random_password" "db" {
  length           = 40
  special          = true
  override_special = "_-+=@#"
}

resource "mazevault_secret" "db_password" {
  project_id  = mazevault_project.backend.id
  key         = "POSTGRES_PASSWORD"
  environment = "production"

  value_wo         = ephemeral.random_password.db.result
  value_wo_version = 1
}

resource "mazevault_secret_link" "db_link" {
  secret_id      = mazevault_secret.db_password.id
  integration_id = mazevault_integration.azure_kv.id
  link_type      = "database"
  metadata = {
    db_user = "app_user"
    db_host = "db.prod.example.com"
    db_name = "appdb"
  }
}

resource "mazevault_rotation_config" "db" {
  secret_id             = mazevault_secret.db_password.id
  rotation_interval_days = 30
  enabled               = true
  notification_emails   = ["ops@example.com"]
}

# Doručení otočené hodnoty do Kubernetes secretu po každé rotaci.
resource "mazevault_secret_rotation_target" "k8s" {
  secret_id   = mazevault_secret.db_password.id
  target_type = "kubernetes_secret"
  priority    = 10
  enabled     = true
  config_json = jsonencode({
    namespace   = "production"
    secret_name = "app-db-credentials"
    secret_key  = "POSTGRES_PASSWORD"
    agent_id    = "uuid-vaseho-agenta"
  })
}

# Otočení hesla přímo na databázi.
resource "mazevault_secret_rotation_target" "postgres" {
  secret_id   = mazevault_secret.db_password.id
  target_type = "database_password"
  priority    = 20
  enabled     = true
  config_json = jsonencode({
    db_provider                = "postgres"
    host                       = "db.prod.example.com"
    port                       = 5432
    database                   = "appdb"
    username                   = "app_user"
    admin_credential_secret_id = "uuid-admin-secretu"
  })
}

Stavově bezpečné tajné hodnoty¶

Pro tajné hodnoty spravované Terraformem preferujte value_wo s Terraform 1.11+ ephemeral resources. Provider načte hodnotu z konfigurace během apply, odešle ji do MazeVaultu a neuloží ji do Terraform plánu ani stavu. Při odeslání nové write-only hodnoty navyšte value_wo_version.

ephemeral "random_password" "api" {
  length           = 48
  special          = true
  override_special = "_-+=@#"
}

resource "mazevault_secret" "api_password" {
  project_id       = mazevault_project.backend.id
  key              = "API_PASSWORD"
  environment      = "production"
  value_wo         = ephemeral.random_password.api.result
  value_wo_version = 1
}

Starší argument value zůstává podporovaný pro existující konfigurace, ale Terraform ukládá sensitive hodnoty do stavu. Pokud stav nesmí obsahovat plaintext, nečtěte tajné hodnoty zpět přes data source mazevault_secret.

Generování tajných hodnot na straně serveru¶

Místo zadání value přidejte blok generate { ... } a MazeVault vytvoří hodnotu za vás pomocí kryptograficky bezpečných znaků bezpečných pro DB/URL. Musí být nastaveno právě jedno z value, value_wo nebo generate. Vygenerovaný plaintext se nikdy nevrací do Terraformu (nikdy nevstoupí do stavu); v režimu Orchestrator je předán přímo externímu správci tajných hodnot.

resource "mazevault_secret" "api_key" {
  project_id  = mazevault_project.backend.id
  key         = "API_KEY"
  environment = "production"

  generate {
    length          = 48
    include_symbols = true
  }
}

Pole `generate`	Výchozí	Popis
`length`	`40`	Délka generované hodnoty
`include_upper`	`true`	Zahrnout velká písmena
`include_lower`	`true`	Zahrnout malá písmena
`include_digits`	`true`	Zahrnout číslice
`include_symbols`	`true`	Zahrnout symboly bezpečné pro DB/URL
`excluded_chars`	—	Znaky, které se mají z výsledku vyloučit

Integrace Azure Key Vault a Entra¶

Typovaná pole Azure DevOps azure_* jsou zastaralá (integrace Azure DevOps již nejsou podporovány, API je odmítá) a budou odstraněna v příští hlavní verzi provideru. mazevault_integration přijímá také obecnou mapu config (bez tajných hodnot) a mapu sensitive_config určenou pouze pro zápis (tajné hodnoty, které se ze serveru nikdy nečtou zpět) a interactive_auth_method. To umožňuje integrace s Azure Key Vault a Microsoft Entra.

resource "mazevault_integration" "kv" {
  project_id    = mazevault_project.backend.id
  name          = "prod-keyvault"
  type          = "azure_key_vault"
  provider_name = "azure_keyvault"
  environment   = "production"

  config = {
    vault_url   = "https://myvault.vault.azure.net/"
    auth_method = "client_secret"
    tenant_id   = var.tenant_id
    client_id   = var.client_id
  }

  sensitive_config = {
    client_secret = var.client_secret
  }
}

Rotace přihlašovacích údajů Entra ID¶

post_rotation_actions je jediný zdroj pravdy pro doručení po rotaci. Pokud nedefinujete žádné bloky akcí, nic se nedoručí. Zápis zpět do Key Vault a obnovení Spring Boot se vyjadřují jako akce zde — nikoli jako samostatná pole nejvyšší úrovně. Atributy kv_integration_ids, secret_name, spring_endpoints a webhook_urls jsou nyní jen pro čtení a odvozené (mirror) z těchto akcí.

resource "mazevault_entra_rotation_config" "app" {
  credential_id               = var.entra_credential_id
  rotation_days_before_expiry = 30

  post_rotation_actions {
    type = "azure_keyvault"
    config = {
      integration_id = mazevault_integration.kv.id
      secret_name    = "app-client-secret"
    }
  }

  post_rotation_actions {
    type   = "spring_actuator_refresh"
    config = { actuator_url = "https://app.example.com/actuator/refresh" }
  }
}

Příklad: Automatizace životního cyklu certifikátů¶

Vydá TLS certifikát prostřednictvím CA účtu a nastaví automatické obnovení. mazevault_certificate_template je Project Template kategorie certificates: vytvoří se na úrovni organizace (odvozené z project_id) a zobrazí se ve frontendovém pohledu Project Templates pro projekty správy certifikátů (type = "certificate").

resource "mazevault_project" "pki" {
  organization_id = mazevault_organization.acme.id
  name            = "PKI"
  type            = "certificate"
}

resource "mazevault_ca_account" "digicert" {
  organization_id = mazevault_organization.acme.id
  name            = "DigiCert Production"
  provider_type   = "digicert"
  api_key         = var.digicert_api_key
  base_url        = "https://www.digicert.com"
}

Šablony certifikátů jsou Project Templates kategorie certificates

mazevault_certificate_template vytvoří Project Template s kategorií certificates na úrovni organizace (odvozené z project_id), takže se zobrazí v pohledu Project Templates. MazeVault automaticky vytvoří podkladovou šablonu certifikátu, dostupnou jako computed certificate_template_id. validity_period je celý počet dní, zapsaný jako <n>d (např. 365d) nebo v hodinách (např. 8760h); jiné hodnoty plán odmítne; type je subtyp certifikátu (např. ssl_tls).

ACME CA účty (Let's Encrypt / ZeroSSL / vlastní)¶

ACME provideři používají email a directory_url (a při použití External Account Binding také eab_kid / eab_hmac_key) místo api_key. Každý neinterní provider musí zadat přihlašovací údaje — provider to ověří na straně klienta a při jejich chybějícím zadání vrátí jasnou chybu ještě před voláním serveru. directory_url je povinné pro vlastní acme provider a pro letsencrypt a zerossl se doplní automaticky. ACME politika výzvy (challenge) se nastavuje na šabloně certifikátu přes challenge_type.

resource "mazevault_ca_account" "letsencrypt" {
  organization_id = mazevault_organization.acme.id
  name            = "Let's Encrypt"
  provider_type   = "letsencrypt"
  email           = "pki@example.com"
}

resource "mazevault_ca_account" "zerossl" {
  organization_id = mazevault_organization.acme.id
  name            = "ZeroSSL"
  provider_type   = "zerossl"
  email           = "pki@example.com"
  eab_kid         = var.zerossl_eab_kid
  eab_hmac_key    = var.zerossl_eab_hmac_key
}

resource "mazevault_ca_account" "internal_acme" {
  organization_id = mazevault_organization.acme.id
  name            = "Internal ACME"
  provider_type   = "acme"
  email           = "pki@example.com"
  directory_url   = "https://ca.internal.example.com/acme/acme/directory"
}

resource "mazevault_certificate_template" "acme_web" {
  project_id      = mazevault_project.pki.id
  name            = "ACME Web TLS"
  type            = "tls_server"
  validity_period = "2160h"
  # auto (výchozí) | dns-01 | http-01 | tls-alpn-01
  challenge_type  = "dns-01"
}

U externích komerčních CA, které vyžadují doménovou validaci (například SSLMarket), se metoda validace nastavuje na šabloně přes dcv_method (email, dns nebo file). Prázdná hodnota použije výchozí nastavení providera/účtu. dcv_method je ignorováno interními a ACME issuery.

Veřejné TLS certifikáty platí nejvýše 200 dní, zatímco objednávka u SSLMarketu je víceleté předplatné: v jeho rámci vydává CA navazující certifikáty sama a MazeVault je přebírá (stejný klíč, kompletní nasazení, předání až po úspěchu) bez založení nové placené objednávky. Navažte šablonu na účet a produkt, zvolte délku předplatného přes order_years a nastavte technický kontakt, který CA dostane s každou objednávkou:

resource "mazevault_ca_account" "sslmarket" {
  organization_id = mazevault_organization.acme.id
  name            = "SSLmarket"
  provider_type   = "sslmarket"
  api_key         = var.sslmarket_api_token

  settings = {
    dv_auth_method         = "dns"
    order_wait_alert_hours = "24"
    # MazeVault umístí TXT záznamy _dnsauth sám; bez DNS poskytovatele založí
    # tiket v ticketing integraci organizace.
    dns_solver_type   = "azure_dns"
    dns_solver_config = jsonencode({ subscription_id = var.sub_id, resource_group = "rg-dns", zone = "example.cz" })
    owner_name        = "Example a.s."
    owner_country     = "CZ"
    invoice_email     = "invoices@example.cz"
    tech_email        = "pki@example.cz"
  }
}

resource "mazevault_certificate_template" "sslmarket_dv" {
  project_id      = mazevault_project.pki.id
  name            = "Veřejné TLS (SSLMarket)"
  type            = "ssl_tls"
  validity_period = "4800h" # 200 dní
  ca_account_id   = mazevault_ca_account.sslmarket.id
  ca_product_id   = var.sslmarket_product_id # ze synchronizovaného katalogu
  dcv_method      = "dns"
  order_years     = 2
  tech_contact = {
    firstname = "Jana"
    lastname  = "Nováková"
    email     = "pki@example.cz"
  }
}

# Žádost může šablonu pro jeden certifikát přepsat; prázdné = zdědit.
resource "mazevault_certificate" "shop" {
  common_name = "shop.example.cz"
  project_id  = mazevault_project.pki.id
  template_id = mazevault_certificate_template.sslmarket_dv.certificate_template_id
  order_years = 3
}

Složená nastavení se ověřují proti katalogu produktů před založením objednávky (metoda validace, počet SAN, wildcard, maximum let), takže neplatná kombinace selže při terraform apply, nikdy jako placená objednávka. Zdroj mazevault_certificate u takových asynchronních objednávek vrací čekající certifikát; MazeVault ověří doménu a materiál doplní, jakmile CA vydá.

Pro použití ACME endpointu SSLMarketu místo objednávkového API nastavte na účtu settings = { mode = "acme", acme_product_code = "...", acme_certificate_validity_days = "90" } (pouze HTTP-01); MazeVault založí ACME klíč a EAB údaje při připojení.

Interní kořenovou CA organizace lze spravovat zdrojem mazevault_ca. Každá organizace má nejvýše jednu interní CA; její parametry jsou neměnné (změna je nahrazuje novou CA) a zrušení zdroje ji měkce smaže — smazání je odmítnuto, dokud existují aktivní certifikáty vydané touto CA.

resource "mazevault_ca" "org_root" {
  organization_id = mazevault_organization.acme.id
  name            = "ACME Internal CA"
  valid_years     = 10
  key_size        = 4096
}

resource "mazevault_renewal_policy" "default" {
  organization_id  = mazevault_organization.acme.id
  name             = "30denní předstih"
  lead_days        = 30
  auto_approve     = true
  notify_emails    = "ops@example.com"
}

resource "mazevault_certificate_template" "web_tls" {
  project_id      = mazevault_project.pki.id
  name            = "Web TLS 1Y"
  type            = "ssl_tls"
  validity_period = "8760h"
  key_usage       = ["digitalSignature", "keyEncipherment"]
}

resource "mazevault_certificate" "api_tls" {
  common_name                = "api.example.com"
  ttl                        = "8760h"
  key_size                   = 2048
  organization_ca_account_id = mazevault_ca_account.digicert.id
}

output "api_cert_pem" {
  value     = mazevault_certificate.api_tls.certificate_pem
  sensitive = false
}

output "api_key_pem" {
  value     = mazevault_certificate.api_tls.private_key_pem
  sensitive = true
}

Vydání interní CA organizace a nasazení do Key Vaultu: certifikát lze vydat interní CA organizace (mazevault_ca), přiřadit k projektu a při obnově doručit do Azure Key Vaultu přes položku post_rotation_actions. Kompletní argumenty, atributy a příklady najdete v dokumentaci resourceů provideru: mazevault_ca, mazevault_certificate a mazevault_certificate_rotation_config.

Čtení certifikátu včetně řetězce vydavatelů¶

Data source mazevault_certificate použijte tam, kde jiný modul potřebuje veřejný certifikát spolu s řetězcem CA — například pro předání podřízené CA (a jejího rootu) do trust store spravovaného mimo MazeVault:

data "mazevault_certificate" "issuing_ca" {
  id = var.issuing_ca_certificate_id
}

resource "local_file" "issuing_ca_bundle" {
  content  = data.mazevault_certificate.issuing_ca.certificate_pem # certifikát + řetězec vydavatelů
  filename = "${path.module}/issuing-ca-fullchain.pem"
}

certificate_pem a chain_pem vždy obsahují efektivní řetězec vydavatelů — tentýž, který vrací export API a který nasazují agenti. Řetězec zachycený při importu nebo vydání certifikátu se vrací beze změny (chain_source = "stored"). Pokud žádný řetězec uložen není, MazeVault hledá vydavatele mezi CA certifikáty spravovanými v téže organizaci a použije ho jen tehdy, když kryptograficky ověří podpis certifikátu (chain_source = "inventory"). chain_complete říká, zda řetězec končí self-signed rootem.

Příklad: RBAC a servisní účet¶

Vytvoří CI/CD servisní účet s oprávněním jen pro čtení k určitému projektu.

resource "mazevault_role" "ci_readonly" {
  name        = "ci-readonly"
  description = "Přístup jen pro čtení pro deployment pipeline"
  permissions = ["secrets:read", "certificates:read", "projects:read"]
}

resource "mazevault_service_identity" "github_actions" {
  display_name = "GitHub Actions CI"
  description  = "Servisní účet jen pro čtení pro produkční deploymenty"
  owner_email  = "platform@example.com"
}

resource "mazevault_service_identity_role" "github_actions_readonly" {
  service_identity_id = mazevault_service_identity.github_actions.id
  role_id             = mazevault_role.ci_readonly.id
  project_id          = var.project_id
}

resource "mazevault_api_token" "ci_token" {
  name   = "github-actions-prod"
  scopes = ["secrets:read", "certificates:read"]
}

output "ci_client_id" {
  value = mazevault_service_identity.github_actions.client_id
}

output "ci_client_secret" {
  value     = mazevault_service_identity.github_actions.client_secret
  sensitive = true
}

Service identity patří do organizace přihlašovacích údajů provideru; mazevault_service_identity ji exportuje jako organization_id. mazevault_service_identity_role jí přidělí roli v této organizaci (bez project_id) nebo v jednom z jejích projektů; rozsah v jiné organizaci je odmítnut a přidělit lze jen oprávnění, která mají vaše přihlašovací údaje v daném rozsahu samy.

Příklad: Synchronizační pravidla a šablony rotace¶

Průběžně načítejte tajné hodnoty z Azure Key Vault do projektu MazeVault a samostatně udržujte katalogový záznam schválených nastavení rotace v rozsahu organizace.

Bez automatické aplikace

Resource šablony rotace spravuje pouze katalogový záznam. Hodnoty automaticky neaplikuje ani nedědí do konfigurací rotace; každý rotační prostředek nakonfigurujte explicitně.

Číselná pole

Pole rotation_interval_days, lead_time_days, grace_period_days, max_retry_attempts, retry_delay_seconds a timeout_minutes musí být nezáporná celá čísla. Explicitní 0 je platná hodnota a je zachována; pole vynechejte, chcete-li ponechat výchozí hodnotu serveru (při vytvoření) nebo hodnotu beze změny (při aktualizaci).

# Opakovaně použitelná šablona politiky rotace
resource "mazevault_rotation_template" "standard_90d" {
  name                   = "standardní-90-dní"
  description            = "Standardní 90denní rotace se 14denním předstihem pro certifikáty"
  rotation_interval_days = 90
  lead_time_days         = 14
  grace_period_days      = 3
  max_retry_attempts     = 3
  retry_delay_seconds    = 30
  timeout_minutes        = 30
  is_default             = true
  # project_id           = mazevault_project.backend.id  # volitelné: omezení na jeden projekt
}

# Stahování tajných hodnot z Azure KV do produkčního prostředí
resource "mazevault_sync_rule" "azure_kv_pull" {
  name               = "azure-kv-produkce-pull"
  project_id         = mazevault_project.backend.id
  integration_id     = mazevault_integration.azure_kv.id
  target_environment = "production"
  source_path        = "secrets/app/"
  sync_direction     = "pull"
  sync_mode          = "incremental"
  conflict_strategy  = "external_wins"
}

# Akce po rotaci cílená na konkrétní gateway
resource "mazevault_rotation_workflow" "db_with_gateway" {
  secret_id             = mazevault_secret.db_password.id
  environment           = "production"
  rotation_interval_days = 90

  post_rotation_actions {
    type       = "azure_keyvault"
    order      = 1
    on_failure = "rollback"
    gateway_id = "gateway-eu-west-01"
    config = {
      vault_url   = "https://myvault.vault.azure.net"
      secret_name = "db-password"
    }
  }

  post_rotation_actions {
    type              = "spring_actuator_refresh"
    order             = 2
    on_failure        = "continue"
    target_environment = "production"
    config = {
      url = "https://api.example.com/actuator/refresh"
    }
  }
}

Příklad: Úrovně prostředí¶

Definujte úrovně prostředí pro organizaci. name a slug jsou neměnné — změna kteréhokoli z nich vynutí znovuvytvoření prostředí. V místě lze měnit pouze is_production a incident_auto_escalation.

resource "mazevault_environment" "production" {
  organization_id          = mazevault_organization.acme.id
  name                     = "production"
  slug                     = "prod"
  is_production            = true
  incident_auto_escalation = true
}

Příklad: Správa externích API tokenů¶

Mnoho externích systémů (Jira, Signi, …) vydává dlouhodobé API tokeny, které lze obnovit pouze ručně v jejich vlastním GUI. mazevault_token umožňuje takový token zaevidovat s povinným datem expirace, takže MazeVault vyvolá incident dříve, než token vyprší. Hodnota se ukládá šifrovaně (nebo je v Orchestrator Mode offloadována do vašeho správce tajemství). Tato funkce vyžaduje licenci PoC nebo Enterprise. Workflow v UI, upozorňování a cíle nasazení popisuje průvodce Správa tokenů; REST kontrakt je v API pro tokeny.

resource "mazevault_token" "jira" {
  name             = "jira-automation-token"
  token_provider   = "jira"                 # volný textový štítek; jira/signi mají v UI vlastní ikony
  description      = "CI automatizační token pro Jira Cloud"
  value_wo         = var.jira_token          # Terraform 1.11+; není v plánu ani stavu
  value_wo_version = 1                       # zvýšení hodnoty nahradí token
  expires_at       = "2027-01-01T00:00:00Z" # povinné
  lead_time_days   = 30                      # upozornit 30 dní před expirací
}

# Vypíše tokeny, které vstoupily do okna upozornění.
data "mazevault_tokens" "all" {}

output "tokens_needing_renewal" {
  value = [for t in data.mazevault_tokens.all.tokens : t.name if t.days_until_expiry <= t.lead_time_days]
}

Po obnově tokenu v externím systému aktualizujte jeho hodnotu přes renew flow v MazeVault UI/API (který zároveň znovu nasadí případné agentní cíle), nikoli v Terraformu. Změna value v Terraformu vynutí znovuvytvoření zdroje.

Zastaralý argument value zůstává dostupný pro existující konfigurace, Terraform jej ale ukládá do stavu. Nenahrazujte jej na existujícím resource automaticky za value_wo: změna vytvoří nový token, změní jeho ID a smaže jeho MazeVault deployment cíle. value_wo používejte pro nové tokeny. Při záměrné migraci nejprve inventarizujte všechny cíle a znovu je vytvořte v servisním okně. Úprava HCL neodstraní plaintext z historických verzí vzdáleného stavu; externí token vyrotujte a postupujte podle retenčního a purge procesu použitého state backendu.

Příklad: Onboarding čerstvé instalace¶

Nová instalace MazeVault začíná s jednou organizací a bez politik. Zdroje níže z ní udělají řízenou platformu jedním terraform apply: prostředí, organizační politiky Configuration Managementu, Project Templates, interní kořenovou CA a účet Smallstep step-ca. Jediný krok, který Terraform provést nemůže, je úplně první přihlášení a vytvoření API tokenu (provider ho potřebuje ke svému běhu) — proveďte ho jednou přes bootstrap API nebo UI a token předejte provideru.

Licence

mazevault_config_template vyžaduje licenční funkci config_management (úrovně PoC a Enterprise). Ostatní zdroje v této sekci fungují na všech úrovních.

Prostředí¶

locals {
  environments = {
    dev  = { name = "DEV", production = false }
    itg  = { name = "ITG", production = false }
    stg  = { name = "STG", production = false }
    tst  = { name = "TST", production = false }
    pre  = { name = "PRE", production = false }
    prod = { name = "PRO", production = true }
  }
}

resource "mazevault_environment" "tier" {
  for_each        = local.environments
  organization_id = var.organization_id
  name            = each.value.name
  slug            = each.key
  is_production   = each.value.production
}

Politiky Configuration Managementu¶

Dokumenty politik jsou typované: template_type vybírá backendový validátor a definition nese vlastní dokument. Chyby validace se hlásí už při plánu včetně názvu chybného pole, takže špatná politika se nikdy nedostane do databáze.

resource "mazevault_config_template" "naming" {
  organization_id = var.organization_id
  name            = "Firemní jmenná konvence"
  template_type   = "naming_convention"

  definition = jsonencode({
    patterns = {
      project   = "{company}-{env}-{project}"
      key_vault = "{company}{env}{project}kv{index}"
      secret    = "{project}-{purpose}"
    }
    non_prod_prefix       = "npr"
    non_prod_environments = ["dev", "itg", "stg", "tst", "pre"]
    variables = [
      { name = "company", required = true, max_length = 4, pattern = "^[a-z]{2,4}$" },
      { name = "env", required = true },
      { name = "project", required = true, max_length = 12 },
      { name = "purpose", required = false },
      { name = "index", required = false, default = "01" },
    ]
    resource_constraints = {
      key_vault = { max_length = 24, allowed_chars = "^[a-z0-9-]+$" }
    }
  })
}

resource "mazevault_config_template" "secret_patterns" {
  organization_id = var.organization_id
  name            = "Přiřazení hesel"
  template_type   = "secret_pattern"
  definition = jsonencode({
    patterns          = [{ name = "password-assignment", type = "regex", regex = "(?i)password\\s*=", severity = "high" }]
    entropy_threshold = 3.5
    min_length        = 8
    max_length        = 128
  })
}

Podporované hodnoty template_type: naming_convention, secret_pattern, secret_naming_policy, discovery_policy, exclusion_rule, resource_visibility_policy (pouze administrátoři) a parser.

Project Templates¶

Project Templates předkonfigurují způsob zakládání nových projektů. Šablony kategorie secrets a keys používají mazevault_project_template; šablony kategorie certificates používají mazevault_certificate_template, která navíc zakládá vydávací certifikátovou šablonu.

resource "mazevault_project_template" "secrets_kv" {
  organization_id = var.organization_id
  name            = "Secrets — Azure Key Vault"
  category        = "secrets"
  subtype         = "secrets_manager"
  protocol_config = jsonencode({ provider = "azure_key_vault", rotation_days = 30 })
}

Interní kořenová CA a Smallstep step-ca¶

resource "mazevault_ca" "root" {
  organization_id = var.organization_id
  name            = "Firemní kořenová CA"
  key_algorithm   = "RSA"
  key_size        = 4096
  valid_years     = 10
}

resource "mazevault_ca_account" "stepca" {
  organization_id = var.organization_id
  name            = "Sdílená step-ca"
  provider_type   = "smallstep"

  settings = {
    server_url       = var.step_ca_url
    provisioner_name = "mazevault"
    provisioner_type = "JWK"
    root_fingerprint = var.step_ca_root_fingerprint
    default_ttl      = "24h"
  }

  credentials_wo = {
    provisioner_password = var.step_ca_provisioner_password
  }
  credentials_wo_version = 1
}

Tajné údaje nikdy nepatří do settings

settings se ukládají jako plaintext metadata CA účtu a vrací je API. Hesla, tokeny a klíče vkládejte do credentials_wo (write-only, Terraform 1.11+, nikdy se neukládá do Terraform state; po rotaci zvyšte credentials_wo_version), případně na starším Terraformu do citlivé mapy credentials — provider klíče vypadající jako tajné údaje v settings odmítne už při plánu.

Entra ID: výběr aplikací do projektu a rotace jejich client secretu¶

resource "mazevault_integration" "entra" {
  project_id    = mazevault_project.identity.id
  name          = "Entra ID — firemní tenant"
  type          = "identity_provider"
  provider_name = "entra_id"
  environment   = "prod"

  config = {
    tenant_id   = var.tenant_id
    client_id   = var.automation_client_id
    auth_method = "client_secret"
  }
  sensitive_config = { client_secret = var.automation_client_secret }
}

resource "mazevault_entra_integration_scope" "payments" {
  integration_id = mazevault_integration.entra.id
  selected_apps = [{
    app_id       = var.payments_app_client_id
    object_id    = var.payments_app_object_id
    display_name = "APP_PAYMENTS_PROD"
  }]
}

data "mazevault_entra_app_registration" "payments" {
  integration_id = mazevault_integration.entra.id
  app_id         = var.payments_app_client_id
  depends_on     = [mazevault_entra_integration_scope.payments]
}

resource "mazevault_entra_rotation_config" "payments" {
  credential_id           = data.mazevault_entra_app_registration.payments.primary_credential_id
  staged_rotation_enabled = true

  post_rotation_actions {
    type  = "azure_keyvault"
    order = 1
    config = {
      integration_id = mazevault_integration.kv.id
      secret_name    = "payments-client-secret"
    }
  }
}

Zdroj scope po každém apply synchronizuje vybrané aplikace z Microsoft Graph, takže datový zdroj dokáže primary_credential_id vyřešit ve stejném běhu. Automatizační identita nastavená na integraci potřebuje aplikační oprávnění Application.ReadWrite.OwnedBy a vlastnictví vybraných aplikací — nikdy jako automatizační identitu nepoužívejte aplikaci, která je sama cílem rotace.

Úschova privátního klíče v Orchestrator módu¶

Instance v Orchestrator módu neukládají privátní klíče lokálně. Požádejte backend, aby serverově generované klíče odložil do integrace secret manageru:

resource "mazevault_certificate" "app" {
  common_name        = "app.example.com"
  project_id         = mazevault_project.pki.id
  template_id        = mazevault_certificate_template.web_tls.certificate_template_id
  key_storage_mode   = "external"
  key_integration_id = mazevault_integration.kv.id
}

Přehled zdrojů¶

Kompletní dokumentace atributů každého zdroje je dostupná na Terraform Registry.

Zdroj	Popis
`mazevault_organization`	Nejvyšší úroveň organizace
`mazevault_project`	Projekt (hranice RBAC, sdružuje tajné hodnoty/certifikáty)
`mazevault_project_settings`	Provozní nastavení projektu (retence, synchronizace, notifikace)
`mazevault_secret`	Šifrovaná tajná hodnota s volitelnou rotací
`mazevault_secret_link`	Propojí tajnou hodnotu s externí integrací pro zápis
`mazevault_shared_secret`	Jednorázový sdílecí odkaz na tajnou hodnotu
`mazevault_rotation_config`	Kompletní konfigurace rotační pipeline pro tajnou hodnotu (v2: `rotation_interval_days` nahrazuje `ttl_hours`/`rotation_strategy`)
`mazevault_rotation_workflow`	Jednoduchý plán rotace pro tajnou hodnotu
`mazevault_rotation_template`	Opakovaně použitelná šablona politiky rotace
`mazevault_secret_rotation_target`	Strukturovaný deployment cíl v rotační pipeline tajné hodnoty (K8s, DB, Agent, cloudový vault)
`mazevault_certificate_rotation_config`	Konfigurace automatické rotace a obnovy pro konkrétní certifikát
`mazevault_entra_rotation_config`	Plánování rotace přihlašovacích údajů Entra ID (dny před vypršením, staged rotace)
`mazevault_sync_rule`	Synchronizační pravidlo mezi MazeVault a externím poskytovatelem tajných hodnot (KV, Azure KV, GitHub, …)
`mazevault_certificate`	Certifikát vydaný nebo sledovaný v MazeVault
`mazevault_certificate_template`	Opakovaně použitelná šablona pro vydávání certifikátů
`mazevault_ca`	Interní kořenová CA organizace (jedna na organizaci)
`mazevault_ca_account`	Integrace nebo reference CA účtu pro externí providery, self-hosted providery a interní CA účet
`mazevault_renewal_policy`	Zásada automatického obnovení certifikátů
`mazevault_integration`	Externí úložiště tajných hodnot / deployment cíl (Azure KV, AWS SM, K8s, …)
`mazevault_integration_group`	Směrování integrací pro více prostředí
`mazevault_consistency_group`	Monitoring shody tajných hodnot napříč prostředími
`mazevault_role`	Vlastní RBAC role
`mazevault_group_mapping`	Mapování skupiny externího IdP na roli MazeVault
`mazevault_user`	Uživatelský účet
`mazevault_user_role`	Přiřazení role uživateli v projektu
`mazevault_service_identity`	Strojová identita (OAuth2 klient)
`mazevault_service_identity_role`	Přiřazení role service identitě v její organizaci nebo v jednom z jejích projektů
`mazevault_api_token`	Rozsahový API token
`mazevault_identity_provider`	Entra ID / LDAP SSO provider
`mazevault_environment`	Definice prostředí
`mazevault_approval_policy`	Schvalovací workflow pro citlivé operace
`mazevault_keytab`	Kerberos keytab pro autentizaci agenta
`mazevault_token`	Externí API token (Jira, Signi, …) s povinným sledováním expirace
`mazevault_deployment`	Bootstrap balíček pro deployment agenta
`mazevault_config_template`	Šablona správy konfigurace (typovaná JSON definice: vzor secretu, parser, pravidlo vyloučení, discovery nebo visibility politika)
`mazevault_project_template`	Project Template kategorie `secrets` nebo `keys`
`mazevault_entra_integration_scope`	Výběr aplikací Entra ID, které projektová integrace spravuje

Přehled datových zdrojů¶

Datový zdroj	Popis
`mazevault_organization`	Vyhledání organizace podle ID
`mazevault_project`	Vyhledání projektu podle ID
`mazevault_secret`	Čtení tajné hodnoty (citlivé)
`mazevault_certificate`	Čtení certifikátu podle ID
`mazevault_project_certificates`	Seznam certifikátů v projektu
`mazevault_project_cas`	Seznam CA účtů v projektu
`mazevault_project_certificate_templates`	Seznam šablon certifikátů v projektu
`mazevault_project_csrs`	Seznam čekajících CSR v projektu
`mazevault_environments`	Seznam prostředí v organizaci
`mazevault_ca_accounts`	Seznam CA účtů v organizaci
`mazevault_users`	Seznam všech uživatelů
`mazevault_roles`	Seznam všech RBAC rolí
`mazevault_integrations`	Seznam integrací v projektu
`mazevault_audit_logs`	Čtení záznamů audit logu
`mazevault_rotation_executions`	Seznam záznamů o provedení rotace
`mazevault_renewal_queue`	Seznam certifikátů čekajících na obnovení
`mazevault_consistency_status`	Výsledek kontroly shody napříč prostředími
`mazevault_rotation_resources`	Seznam všech zdrojů spravovaných rotací s jejich stavem
`mazevault_rotation_resource_history`	Historie provedení rotace pro konkrétní zdroj
`mazevault_project_rotation_configs`	Seznam všech konfigurace rotace v projektu
`mazevault_tokens`	Seznam spravovaných externích API tokenů s jejich stavem expirace
`mazevault_entra_app_registration`	Vyhledání synchronizované aplikace Entra a ID jejích přihlašovacích údajů

Import existujících zdrojů¶

Přiveďte existující zdroje MazeVault pod správu Terraformu pomocí terraform import. UUID zdrojů jsou viditelné v URL v UI nebo přes GET /api/v1/....

terraform import mazevault_project.backend <project-uuid>
terraform import mazevault_secret.db_password <secret-uuid>
terraform import mazevault_certificate.tls <certificate-uuid>
terraform import mazevault_integration.azure_kv <integration-uuid>
# zdroje vázané na nadřazený objekt používají "<parent_id>/<id>":
terraform import mazevault_deployment.edge <organization-uuid>/<deployment-uuid>
terraform import mazevault_certificate_template.web <project-uuid>/<template-uuid>
terraform import mazevault_shared_secret.handover <share-uuid>/<secret-uuid>

Objekty smazané mimo Terraform¶

Všechny zdroje se řídí stejným pravidlem, když objekt, který spravují, už neexistuje:

Refresh (terraform plan / apply) — 404 z MazeVaultu odebere zdroj ze state a další plán ho vytvoří znovu.
Destroy — 404 se bere jako už smazaný objekt a destroy uspěje.
Jakákoli jiná chyba (401, 403, 5xx, síť) se ohlásí a zdroj zůstane ve state; kvůli přechodnému výpadku se nic znovu nevytváří.

Známá omezení¶

mazevault_role — Role nelze přes MazeVault API smazat. terraform destroy odstraní zdroj pouze z Terraform stavu; role v MazeVault zůstane.
mazevault_organization — Organizace nelze přes MazeVault API smazat. terraform destroy odstraní zdroj s varováním pouze z Terraform stavu a na server nic neposílá; organizace v MazeVault zůstane.
mazevault_deployment — Bootstrap token je vrácen pouze při vytvoření a uchováván ve stavu (citlivé). terraform destroy měkce smaže deployment záznam a zneplatní enrollment token; již registrovaní agenti běží dál. Zrušení externě smazaného záznamu je idempotentní. expires_in_days (výchozí 30, 0 = bez expirace) a max_uses (0 = bez omezení) nastavují platnost a limit použití tokenu pro hromadné nasazení z balíčků; změna kteréhokoli z nich vytvoří nový deployment a token a expires_at ukazuje výslednou expiraci.
mazevault_ca — Spravuje jedinou interní kořenovou CA organizace (organization_id). Všechny parametry jsou neměnné; změna kteréhokoli z nich nahradí CA. Zrušení zdroje interní CA měkce smaže, ale smazání je odmítnuto (HTTP 409), dokud existují aktivní (neodvolané, nevypršelé) certifikáty vydané touto CA. Atributy ocsp_url / crl_url jsou pouze ke čtení a odrážejí URL publikované pro vydané certifikáty.
Atributy, které API neumí změnit, vynucují nahrazení nebo plán odmítnou — mazevault_group_mapping (group_name, role_id), mazevault_secret_link (všechny argumenty), mazevault_shared_secret (ttl_hours, max_views), mazevault_api_token (name, scopes, duration), mazevault_secret (project_id, key, environment), mazevault_integration_group, mazevault_consistency_group a mazevault_integration (project_id) a mazevault_hsm_device (provider_type) při změně naplánují zničení a nové vytvoření, a stejně tak každý zdroj, který na nahrazený odkazuje. Nahrazení secretu smaže jeho historii verzí a znovu zapíše nakonfigurovanou hodnotu (generate vytvoří novou náhodnou hodnotu; hodnota rotovaná na serveru se vrátí), nahrazení API tokenu odvolá starý token a nahrazený sdílený odkaz se odvolá (zničení mazevault_shared_secret sdílení smaže, smazat ho může jen uživatel, který ho vytvořil). mazevault_project.organization_id a display_name, description a permissions u mazevault_role (při stejném name) změnit vůbec nejde: plán skončí chybou, protože nahrazení by smazalo secrety projektu, nebo u role, kterou API neumí změnit ani smazat, nemůže uspět. V terraform plan hledejte must be replaced a mazevault_secret.environment nenechávejte prázdné (prázdné se uloží jako dev a další plán by secret nahradil).
mazevault_shared_secret — provider při vytvoření sdílení načte hodnotu secretu z secret_id a neukládá ji do state; secret, jehož hodnotu server nepřečte (zero-knowledge, pouze názvy, externí), sdílet nejde. share_url je citlivý: kdo má odkaz, přečte si tajnou hodnotu, proto ho Terraform nevypisuje v plánu ani ve výstupu apply. Hodnotu získáte přes terraform output -raw nebo nonsensitive() tam, kde ji předáváte.
mazevault_environment — Když backend vytvoření odmítne, protože prostředí se stejným názvem nebo slugem už existuje, provider ho převezme jen tehdy, když se shodují nakonfigurované is_production a incident_auto_escalation; jinak apply skončí chybou, která rozdílné příznaky vyjmenuje. Prostředí importujte (terraform import <adresa> <organization_id>/<name>) nebo upravte konfiguraci; na existujícím prostředí se nic nezmění.
mazevault_rotation_workflow — ttl_hours musí být kladný násobek 24 (backend ukládá celé dny jako rotation_interval_days); jiné hodnoty plán odmítne. environment se posílá aktualizací hned po vytvoření (endpoint pro vytvoření ho nepřijímá) a čte se zpět ze zdroje rotace. rotation_strategy, target_environment, resource_kind a linked_integrations backend neukládá; state si ponechá nakonfigurované hodnoty.
mazevault_integration — Argument environment je povinný a při změně vynucuje znovuvytvoření zdroje. Backend nepodporuje změnu prostředí přes update; při změně prostředí vždy resource znovu vytvořte.
mazevault_secret_rotation_target — Argument config_json musí být platný JSON objekt. Použijte jsonencode() v Terraformu. Neplatný JSON způsobí diagnostickou chybu v době aplikace (apply). Operace čtení používá skenování seznamu (neexistuje přímý GET-by-ID endpoint). Smazání cíle, který byl externě odstraněn, je idempotentní a proběhne bez chyby.
mazevault_rotation_config (v2.0 BREAKING) — Argumenty environment, rotation_strategy, workflow_steps_json, scope a grace_period_minutes byly odstraněny. Nahraďte ttl_hours za rotation_interval_days. Při upgradu z v1.x spusťte terraform state rm a proveďte re-import.
mazevault_certificate_rotation_config — Neexistuje endpoint pro hard-delete. Destroy nastaví enabled = false a odstraní ze stavu.
mazevault_entra_rotation_config — Neexistuje endpoint pro hard-delete. Destroy nastaví rotation_enabled = false a odstraní ze stavu.
mazevault_entra_integration_scope — Destroy pouze odstraní zdroj ze stavu: backend neumí uchovat prázdný scope selected_apps a provider nikdy implicitně nerozšíří scope na legacy_all. Vazby zaniknou spolu s vlastnící mazevault_integration. Scope se posílá znovu jen při změně vybraných aplikací nebo scope_mode (zápis vrací všechny vazby do stavu pending); neúspěšná synchronizace s Graphem nechá scope sledovaný (synced = false) a při dalším apply se zopakuje.
mazevault_config_template — Vyžaduje licenční funkci config_management. Zdroj nyní odpovídá backendovému kontraktu (template_type + definition); dřívější argumenty content/format proti API nikdy nefungovaly a byly odstraněny.
mazevault_ca_account — settings jsou plaintext metadata; klíče vypadající jako tajné údaje jsou odmítnuty a musí být předány přes write-only mapu credentials.
mazevault_certificate — key_storage_mode = "external" vyžaduje dostupnou integraci secret manageru; Orchestrator mód odmítá local. private_key_pem je vyplněn pouze při úschově local. Plná reference klíče v Key Vaultu je v atributu private_key_reference; key_secret_name si drží jméno, které jste zadali, i když backend musel kvůli kolizi přidat příponu.
mazevault_token — Vyžaduje licenci PoC nebo Enterprise (funkce token_management); jinak API vrací HTTP 403. Pro štítek providera použijte token_provider. Nové resources mají používat value_wo spolu s value_wo_version; legacy value je citlivé, ale zůstává v Terraform stavu. Import spravuje pouze metadata. Obnova hodnoty na místě probíhá přes MazeVault UI/API. project_id je neměnné a každý Terraform replacement zároveň smaže MazeVault deployment cíle tokenu.

Doporučené postupy¶

Vzdálený stav — používejte Terraform Cloud, Azure Blob Storage nebo S3 se zamykáním stavu.
Citlivé výstupy — vždy nastavte sensitive = true u výstupů, které obsahují tajné hodnoty nebo privátní klíče.
Přihlašovací údaje přes proměnné prostředí — používejte MAZEVAULT_API_TOKEN nebo TF_VAR_ prefixované proměnné; nikdy necommitujte tokeny v .tfvars.
Fixujte verzi providera — ~> 1.0 povolí patch aktualizace a zablokuje neočekávané změny hlavní verze.
Skupiny konzistence — přidejte mazevault_consistency_group po provisioningu k detekci drift napříč prostředími dříve, než způsobí incident.
Plánování rotace — používejte rotation_interval_days a schedule (cron) pro nastavení kadence rotace (v2: ttl_hours/rotation_strategy byly odstraněny). Deployment akce po rotaci konfigurujte přes mazevault_rotation_workflow nebo podrobnějším zdrojem mazevault_secret_rotation_target (podporuje K8s, otáčení hesla databáze, synchronizaci agenta a cloudové vaulty). Pro certifikáty použijte mazevault_certificate_rotation_config; pro přihlašovací údaje Entra ID použijte mazevault_entra_rotation_config.
Oddělený stav na prostředí — používejte workspaces nebo oddělené state backendy na prostředí, abyste zabránili nechtěným zápisům napříč prostředími.