Delen via

Gebruiken @akv() voor vervanging van Azure Key Vault-geheimen in Data API Builder

Met Data API Builder (DAB) kunt u geheimen, zoals databaseverbindingsreeksen, buiten het runtimeconfiguratiebestand houden door ze tijdens de laadtijd te vervangen. Oorspronkelijk is dit gedaan met de @env() functie voor omgevingsvariabelen. Vanaf versie 1.6 voegt DAB ondersteuning toe voor Azure Key Vault via de @akv() functie.

Wat @akv() doet.

U kunt rechtstreeks in de configuratie-JSON verwijzen naar een geheim dat is opgeslagen in Azure Key Vault:

{
  "data-source": {
    "connection-string": "@akv('my-connection-secret')"
  }
}

Bij het laden van de configuratie lost DAB de tijdelijke aanduiding op en vervangt deze door de waarde van het geheim, vergelijkbaar met hoe @env('VAR_NAME') werkt. Als het geheim niet kan worden opgehaald, mislukt het laden van de configuratie. Fouten omvatten ontbrekende geheimen of autorisatiefouten.

Configuratiestructuur

Voeg de azure-key-vault sectie toe op het hoofdniveau van uw configuratie:

{
  "azure-key-vault": {
    "endpoint": "https://my-vault-name.vault.azure.net/",
    "retry-policy": {
      "mode": "exponential",
      "max-count": 5,
      "delay-seconds": 2,
      "max-delay-seconds": 30,
      "network-timeout-seconds": 45
    }
  }
}

Eigenschappen

Vastgoed Verplicht Typologie Description
endpoint Ja als u Key Vault gebruikt touw De volledige URL van het Key Vault-eindpunt
retry-policy Nee. Voorwerp Negeert het gedrag voor het opnieuw proberen wanneer Key Vault wordt aangeroepen

Beleidsobject opnieuw proberen

Veld Verstek Opmerkingen
mode exponential Toegestane waarden: fixed of exponential
max-count 3 Moet groter zijn dan 0
delay-seconds 1 Moet groter zijn dan 0
max-delay-seconds 60 Moet groter zijn dan 0, maximum voor exponentiële terugval
network-timeout-seconds 60 Moet groter zijn dan 0

Beleidsmodi voor opnieuw proberen

Wijze Gedrag
fixed Wacht een constante tijd delay-seconds tussen pogingen tot max-count
exponential Verdubbelt de vertraging totdat max-delay-seconds of max-count wordt bereikt.

Lokale ontwikkeling: .akv-bestanden

Voor ontwikkeling zonder Azure Key Vault gebruikt u een .akv bestand om geheimen te simuleren. Opmaak is name=value per regel:

my-connection-secret=Server=.;Database=AppDb;User Id=app;Password=local-dev;
api-key=dev-api-key-123

Opmerking

Als u een lokaal .akv bestand opgeeft voor ontwikkeling, worden de vermeldingen ervan gebruikt om te voldoen aan @akv(zoekacties voor 'secret-name') zonder een netwerkoproep naar Azure Key Vault te maken.

Richtsnoeren:

  • Houd .akv buiten versiebeheer
  • Geheime namen moeten overeenkomen met de namen die worden gebruikt in @akv('name')

Azure Key Vault-instellingen toevoegen met CLI

U kunt Key Vault-instellingen configureren met behulp van de CLI:

dab configure \
  --azure-key-vault.endpoint "https://my-vault.vault.azure.net/" \
  --azure-key-vault.retry-policy.mode exponential \
  --azure-key-vault.retry-policy.max-count 5 \
  --azure-key-vault.retry-policy.delay-seconds 2 \
  --azure-key-vault.retry-policy.max-delay-seconds 30 \
  --azure-key-vault.retry-policy.network-timeout-seconds 45 \
  --config dab-config.json

Validering:

  • Opnieuw proberen-beleidsvelden zonder een eindpunt veroorzaken een validatiefout.
  • Optionele parameters voor opnieuw proberen moeten positieve gehele getallen zijn

Gebruiken @akv() in de configuratie

Basisvervanging

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@akv('primary-sql-connection')"
  }
}

Gemengd met @env()

{
  "data-source": {
    "database-type": "@env('DB_TYPE')",
    "connection-string": "@akv('sql-connection')"
  },
  "runtime": {
    "rest": { "enabled": true }
  }
}

Opmerking

Bij het opstarten vinden @env() vervangingen plaats voordat @akv() vervangingen plaatsvinden.

Parameters voor opgeslagen procedures

{
  "entities": {
    "RunJob": {
      "source": {
        "object": "dbo.RunJob",
        "type": "stored-procedure",
        "parameters": {
          "apiKey": "@akv('job-runner-apikey')"
        }
      },
      "permissions": [
        { "role": "anonymous", "actions": [ "execute" ] }
      ]
    }
  }
}

Probleemoplossingsproces

Symptoom Steps
Geheim niet gevonden Naam, bestaan in kluis en identiteitsmachtigingen controleren
Ongeldige waarde voor opnieuw proberen Een positief geheel getal gebruiken of verwijderen om standaardwaarden te gebruiken
Configuratie-update mislukt Logboeken controleren op validatiefouten
@akv() niet vervangen Bevestig eindpunt, naam van het geheim en dat geheimoplossing is ingeschakeld
401/403 van Key Vault Identiteitstoewijzing en machtigingen controleren

Volledige voorbeeldconfiguratie

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@akv('primary-sql-connection')"
  },
  "azure-key-vault": {
    "endpoint": "https://my-vault.vault.azure.net/",
    "retry-policy": {
      "mode": "exponential",
      "max-count": 5,
      "delay-seconds": 2,
      "max-delay-seconds": 30,
      "network-timeout-seconds": 45
    }
  },
  "runtime": {
    "rest": { "enabled": true }
  },
  "entities": {
    "Books": {
      "source": "dbo.Books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

Voorbeeldbestand .akv :

primary-sql-connection=Server=localhost;Database=BooksDb;User Id=app;Password=password;

Belangrijk

Voer geen bestanden met geheimen door .akv . |

Snelzoekgids

Onderdeel Samenvatting
Syntaxis @akv('secret-name')
Eindpunt vereist Yes
Simulatiebestand .akv met name=value lijnen
Mengen met @env() Supported.

Review

Gebruik @akv() dit om geheimen van Azure Key Vault op te lossen. Stel herhalingsbeleid in voor betrouwbaarheid, en gebruik .akv bestanden om geheimen in ontwikkeling te simuleren. Hierdoor blijven gevoelige waarden uit configuratiebestanden en worden consistente ontwikkel- en productiewerkstromen ondersteund.

  • Last updated on