MicroProfile configureren met Azure Key Vault

Deze zelfstudie laat zien hoe u een MicroProfile-toepassing configureert om geheimen op te halen uit Azure Key Vault met behulp van de MicroProfile Config-API's. Ontwikkelaars profiteren van de open standaard MicroProfile Config-API voor het ophalen en injecteren van configuratiegegevens in hun microservices.

Vereisten

• Een Azure-abonnement; Als u nog geen Azure-abonnement hebt, kunt u de voordelen van uw MSDN-abonnee activeren of u aanmelden voor een gratis account.
• Azure CLI voor Unix-achtige omgevingen. Voor dit artikel is alleen de Bash-variant van Azure CLI vereist.
  • Bash

    Installeer Azure CLI en meld u interactief aan met de az login-opdracht om u aan te melden bij Azure voordat DefaultAzureCredential u code gebruikt.

    az login
    

    PowerShell

    Voer de Connect-AzAccount cmdlet uit om te verifiëren met Azure PowerShell. Net als de Azure CLI Connect-AzAccount wordt standaard de standaardwebbrowser gestart om een gebruikersaccount te verifiëren.

    Connect-AzAccount
    

    Visual Studio Code

    Als u Visual Studio Code gebruikt, kunt u zich ook aanmelden bij Azure met de Azure-accountextensie.
  • Voor dit artikel is minimaal versie 2.55.0 van Azure CLI vereist. Als u Azure Cloud Shell gebruikt, is de nieuwste versie al geïnstalleerd.
• Azure Cloud Shell heeft al deze vereisten vooraf geïnstalleerd. Zie quickstart voor Azure Cloud Shell voor meer informatie.
• Als u de opdrachten in deze handleiding lokaal uitvoert (in plaats van Azure Cloud Shell te gebruiken), voert u de volgende stappen uit:
  • Bereid een lokale computer voor waarop unix-achtig besturingssysteem is geïnstalleerd (bijvoorbeeld Ubuntu, macOS of Windows-subsysteem voor Linux).
  • Installeer een Java SE-implementatieversie 17 of hoger (bijvoorbeeld Microsoft-build van OpenJDK).
  • Installeer Maven 3.5.0 of hoger.
  • Installeer cURL.

Verbinding maken het configureren van MicroProfile met Azure Key Vault

Laten we eens kijken naar de kracht van het combineren van Azure Key Vault en de MicroProfile Config-API. Hier volgt een codefragment van een veld in een klasse met aantekeningen en @Inject@ConfigProperty. De name opgegeven in de aantekening is de naam van het geheim dat moet worden opgezocht in Azure Key Vault en wordt defaultValue gebruikt als het geheim niet wordt gedetecteerd. De geheime waarde die is opgeslagen in Azure Key Vault of de standaardwaarde als er geen dergelijk geheim bestaat, wordt tijdens runtime automatisch in het veld geïnjecteerd. Het injecteren van eigenschapswaarden op deze manier biedt tal van voordelen. U hoeft bijvoorbeeld geen waarden meer door te geven in constructors en settermethoden en de configuratie wordt uit de code ge externaliseerd. Een van de krachtigste voordelen is het hebben van afzonderlijke sets waarden voor ontwikkel-, test- en prod-omgevingen.

@Inject
@ConfigProperty(name = "key-name", defaultValue = "Unknown")
String keyValue;

Het is ook mogelijk om de MicroProfile-configuratie imperatief te openen, zoals wordt weergegeven in het volgende voorbeeld:

public class DemoClass {
    @Inject
    Config config;

    public void method() {
        System.out.println("Hello: " + config.getValue("key-name", String.class));
    }
}

In dit voorbeeld wordt de Open Liberty-implementatie van MicroProfile gebruikt. Zie MicroProfile Compatible Implementations voor een volledige lijst met compatibele implementaties. In het voorbeeld ziet u ook hoe u de toepassing in een container kunt containeriseren en uitvoeren in Azure.

In dit voorbeeld wordt de Azure-extensie met lage wrijving gebruikt voor de aangepaste ConfigSource-bibliotheek van MicroProfile Key Vault. Zie de LEESMIJ-bibliotheek voor meer informatie over deze bibliotheek.

Hier volgen de stappen die nodig zijn om deze code uit te voeren op de lokale computer, te beginnen met het maken van een Azure Key Vault-resource.

Een Azure Key Vault-resource maken

U gebruikt de Azure CLI om de Azure Key Vault-resource te maken en deze te vullen met twee geheimen.

Meld u eerst aan bij Azure en stel een abonnement in op het huidige actieve abonnement.

az login
az account set --subscription <subscription-id>

Maak vervolgens een resourcegroep met een unieke naam, bijvoorbeeld mp-kv-rg-ejb010424.

export RESOURCE_GROUP_NAME=mp-kv-rg-ejb010424
az group create \
    --name ${RESOURCE_GROUP_NAME} \
    --location eastus

Maak nu een Azure Key Vault-resource met een unieke naam (bijvoorbeeld k kolomb010424), voeg twee geheimen toe en exporteer de Key Vault-URI als een omgevingsvariabele.

export KEY_VAULT_NAME=kv-ejb010424
az keyvault create \
    --resource-group "${RESOURCE_GROUP_NAME}" \
    --name "${KEY_VAULT_NAME}" \
    --location eastus

az keyvault secret set \
    --vault-name "${KEY_VAULT_NAME}" \
    --name secret \
    --value 1234
az keyvault secret set \
    --vault-name "${KEY_VAULT_NAME}" \
    --name anotherSecret \
    --value 5678

export AZURE_KEYVAULT_URL=$(az keyvault show \
    --resource-group "${RESOURCE_GROUP_NAME}" \
    --name "${KEY_VAULT_NAME}" \
    --query properties.vaultUri \
    --output tsv)
echo $AZURE_KEYVAULT_URL

De omgevingsvariabele AZURE_KEYVAULT_URL is vereist om de bibliotheek later te configureren voor gebruik met het voorbeeld. Houd de terminal open en gebruik deze om de app later lokaal uit te voeren.

Dat is het! Key Vault wordt nu uitgevoerd in Azure met twee geheimen. U kunt nu de voorbeeldopslagplaats klonen en configureren om deze resource in uw app te gebruiken.

Lokaal aan de slag

Dit voorbeeld is gebaseerd op een voorbeeldtoepassing die beschikbaar is op GitHub. Schakel over naar de terminal die u eerder hebt geopend en voer de volgende opdrachten uit om de opslagplaats te klonen en de app lokaal uit te voeren:

git clone https://github.com/Azure/azure-microprofile.git
cd azure-microprofile
git checkout 20240116
cd integration-tests/open-liberty-sample
mvn package liberty:run

Als u een bericht ziet over You are in 'detached HEAD' state, is dit bericht veilig te negeren.

Notitie

De bibliotheek maakt gebruik van standaard Azure-referenties om te verifiëren in Azure.

Omdat u een account lokaal hebt geverifieerd via de Azure CLI-opdracht az login , DefaultAzureCredential wordt dit account geverifieerd voor toegang tot Azure Key Vault.

Wacht totdat de uitvoer vergelijkbaar is met The defaultServer server is ready to run a smarter planet. Open een nieuwe terminal en voer de volgende opdrachten uit om het voorbeeld te testen:

# Get the value of secret "secret" stored in the Azure key vault. You should see 1234 in the response.
echo $(curl -s http://localhost:9080/config/value/secret -X GET)

# Get the value of secret "anotherSecret" stored in the Azure key vault. You should see 5678 in the response.
echo $(curl -s http://localhost:9080/config/value/anotherSecret -X GET)

# Get the names of secrets stored in the Azure key vault. You should see ["anotherSecret","secret"] in the response.
echo $(curl -s http://localhost:9080/config/propertyNames -X GET)

# Get the name-value paris of secrets stored in the Azure key vault. You should see {"anotherSecret":"5678","secret":"1234"} in the response.
echo $(curl -s http://localhost:9080/config/properties -X GET)

U ziet nu de verwachte uitvoer die in de opmerkingen wordt beschreven. Ga terug naar de terminal waarop de app wordt uitgevoerd. Druk op Ctrl + C om de app te stoppen.

De voorbeeld-app onderzoeken

Laten we meer inzicht krijgen in hoe MicroProfile Config werkt in het algemeen en de aangepaste ConfigSource-bibliotheek van MicroProfile Key Vault werkt in het bijzonder.

Bibliotheekafhankelijkheid

Neem aangepaste MicroProfile Key Vault-configuratiebron op in uw app met de volgende Maven-afhankelijkheid:

<dependency>
  <groupId>com.azure.microprofile</groupId>
  <artifactId>azure-microprofile-config-keyvault</artifactId>
</dependency>

Verbinding maken naar Azure Key Vault

De azure-microprofile-config-keyvault bibliotheek verbindt uw app met Azure Key Vault zonder directe afhankelijkheden van Azure-API's te introduceren. De bibliotheek biedt een implementatie van de Configuratiespecificatie van MicroProfile ConfigSource-interface die weet hoe deze kan worden gelezen uit Azure Key Vault. De rest van de implementatie van MicroProfile Config wordt geleverd door de Open Liberty-runtime. Zie Volgende stappen voor een koppeling naar de specificatie.

De bibliotheek definieert de azure.keyvault.url configuratie-eigenschap om uw app te binden aan een specifieke sleutelkluis. Met de configuratiespecificatie van MicroProfile worden de omgevingsvariabelentoewijzingsregels gedefinieerd voor de wijze waarop de waarde voor een configuratie-eigenschap, zoals azure.keyvault.url, tijdens runtime wordt gedetecteerd. Een van deze regels geeft aan dat eigenschappen worden geconverteerd naar omgevingsvariabelen. De eigenschap azure.keyvault.url zorgt ervoor dat de omgevingsvariabele AZURE_KEYVAULT_URL wordt geraadpleegd.

Sleutelklassen in de voorbeeld-app

Laten we de REST-resource bekijken die de voorgaande cURL-opdrachten hebben aangeroepen. Deze REST-resource wordt gedefinieerd in de klasse ConfigResource.java in het integration-tests/open-liberty-sample project.

@Path("/config")
public class ConfigResource {

    @Inject
    private Config config;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Path("/value/{name}")
    public String getConfigValue(@PathParam("name") String name) {
        return config.getConfigValue(name).getValue();
    }

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    @Path("/propertyNames")
    public Set<String> getConfigPropertyNames() {
        ConfigSource configSource = getConfigSource(AzureKeyVaultConfigSource.class.getSimpleName());
        return configSource.getPropertyNames();
    }

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    @Path("/properties")
    public Map<String, String> getConfigProperties() {
        ConfigSource configSource = getConfigSource(AzureKeyVaultConfigSource.class.getSimpleName());
        return configSource.getProperties();
    }

    private ConfigSource getConfigSource(String name) {
        return StreamSupport.stream(config.getConfigSources().spliterator(), false)
                .filter(source -> source.getName().equals(name))
                .findFirst()
                .orElseThrow(() -> new RuntimeException("ConfigSource not found: " + name));
    }
}

De getConfigValue() methode gebruikt de geïnjecteerde Config implementatie om een waarde op te zoeken uit de toepassingsconfiguratiebronnen. Alle waardezoekacties voor de Config implementatie worden gevonden via het zoekalgoritmen dat is gedefinieerd door de Configuratiespecificatie van MicroProfile. De azure-microprofile-config-keyvault bibliotheek voegt Azure Key Vault toe als een configuratiebron.

De getConfigSource() methode voorkomt het zoekalgoritmen en gaat rechtstreeks naar de AzureKeyVaultConfigSource eigenschappen om te lossen. Deze methode wordt gebruikt door de getConfigPropertyNames() en getConfigProperties() methoden.

Uitvoeren in Azure Container Apps

In deze sectie gaat u de app in een container plaatsen, een door de gebruiker toegewezen beheerde identiteit configureren voor toegang tot Azure Key Vault en de container-app implementeren in Azure Container Apps.

Ga terug naar de terminal waar u de app lokaal hebt uitgevoerd en gebruik deze in deze sectie.

Een Azure Container Registry instellen

U gebruikt Azure Container Registry om de app in een container te plaatsen en de app-installatiekopieën op te slaan.

Maak eerst een Azure Container Registry met een unieke naam, bijvoorbeeld acrejb010424.

export ACR_NAME=acrejb010424
az acr create \
    --resource-group $RESOURCE_GROUP_NAME \
    --name $ACR_NAME \
    --sku Basic \
    --admin-enabled

Wacht enkele minuten nadat deze opdracht is geretourneerd voordat u doorgaat.

De app containeriseren

Plaats vervolgens de app in een container en push de app-installatiekopieën naar uw Azure Container Registry. Zorg ervoor dat u zich in het pad van de voorbeeld-app bevindt, bijvoorbeeld azure-microprofile/integration-tests/open-liberty-sample.

az acr build \
    --registry ${ACR_NAME} \
    --image open-liberty-mp-azure-keyvault:latest \
    .

U ziet build-uitvoer die eindigt met een bericht dat vergelijkbaar is Run ID: ca1 was successful after 1m28smet . Als u geen vergelijkbaar bericht ziet, kunt u het probleem oplossen voordat u doorgaat.

Gebruik de volgende opdrachten om verbindingsgegevens op te halen die vereist zijn voor toegang tot de installatiekopieën wanneer u de app later in Azure Container Apps implementeert.

export ACR_LOGIN_SERVER=$(az acr show \
    --name $ACR_NAME \
    --query 'loginServer' \
    --output tsv)
export ACR_USER_NAME=$(az acr credential show \
    --name $ACR_NAME \
    --query 'username' \
    --output tsv)
export ACR_PASSWORD=$(az acr credential show \
    --name $ACR_NAME \
    --query 'passwords[0].value' \
    --output tsv)

Een door de gebruiker toegewezen beheerde identiteit instellen

Zoals eerder vermeld, gebruikt de bibliotheek standaard Azure-referenties om te verifiëren in Azure. Wanneer u de app implementeert in Azure Container Apps, stelt u de omgevingsvariabele AZURE_CLIENT_ID in om DefaultAzureCredential te configureren voor verificatie als een door de gebruiker gedefinieerde beheerde identiteit, die machtigingen heeft voor toegang tot Azure Key Vault en later wordt toegewezen aan Azure Container Apps.

Gebruik eerst de volgende opdrachten om een door de gebruiker toegewezen beheerde identiteit te maken met een unieke naam, bijvoorbeeld uamiejb010424. Zie Een door de gebruiker toegewezen beheerde identiteit maken voor meer informatie.

export USER_ASSIGNED_IDENTITY_NAME=uamiejb010424
az identity create \
    --resource-group ${RESOURCE_GROUP_NAME} \
    --name ${USER_ASSIGNED_IDENTITY_NAME}

Gebruik vervolgens de volgende opdrachten om deze machtigingen te verlenen om geheimen op te halen en weer te geven uit Azure Key Vault. Zie Het toegangsbeleid toewijzen voor meer informatie.

export USER_ASSIGNED_IDENTITY_OBJECT_ID="$(az identity show \
    --resource-group "${RESOURCE_GROUP_NAME}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query 'principalId' \
    --output tsv)"

az keyvault set-policy --name "${KEY_VAULT_NAME}" \
    --resource-group "${RESOURCE_GROUP_NAME}" \
    --secret-permissions get list \
    --object-id "${USER_ASSIGNED_IDENTITY_OBJECT_ID}"

De uitvoer moet de volgende JSON bevatten om als succesvol te worden beschouwd:

"permissions": {
  "certificates": null,
  "keys": null,
  "secrets": [
    "list",
    "get"
  ],
  "storage": null
}

Als de uitvoer deze JSON niet bevat, kunt u het probleem oplossen voordat u doorgaat.

Gebruik vervolgens de volgende opdrachten om de id en client-id van de door de gebruiker toegewezen beheerde identiteit op te halen, zodat u deze later aan uw Azure Container Apps kunt toewijzen voor toegang tot De Azure Key Vault:

export USER_ASSIGNED_IDENTITY_ID="$(az identity show \
    --resource-group "${RESOURCE_GROUP_NAME}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query 'id' \
    --output tsv)"
export USER_ASSIGNED_IDENTITY_CLIENT_ID="$(az identity show \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --resource-group "${RESOURCE_GROUP_NAME}" \
    --query 'clientId' \
    --output tsv)"
echo $USER_ASSIGNED_IDENTITY_ID
echo $USER_ASSIGNED_IDENTITY_CLIENT_ID

De app implementeren in Azure Container Apps

U hebt de app in een container geplaatst en een door de gebruiker toegewezen beheerde identiteit geconfigureerd voor toegang tot Azure Key Vault. U kunt nu de container-app implementeren in Azure Container Apps.

Maak eerst een omgeving voor Azure Container Apps. Een omgeving in Azure Container Apps maakt een veilige grens rond een groep container-apps. Container Apps die in dezelfde omgeving zijn geïmplementeerd, worden geïmplementeerd in hetzelfde virtuele netwerk en schrijven logboeken naar dezelfde Log Analytics-werkruimte. Gebruik de opdracht az containerapp env create om een omgeving te maken met een unieke naam (bijvoorbeeld acaen postvakb010424), zoals wordt weergegeven in het volgende voorbeeld:

export ACA_ENV=acaenvejb010424
az containerapp env create \
    --resource-group $RESOURCE_GROUP_NAME \
    --location eastus \
    --name $ACA_ENV

Gebruik vervolgens de opdracht az containerapp create om een Container Apps-exemplaar te maken met een unieke naam (bijvoorbeeld acaappejb010424) om de app uit te voeren nadat de installatiekopie is opgehaald uit containerregister, zoals wordt weergegeven in het volgende voorbeeld:

export ACA_NAME=acaappejb010424
az containerapp create \
    --resource-group ${RESOURCE_GROUP_NAME} \
    --name ${ACA_NAME} \
    --environment ${ACA_ENV} \
    --image ${ACR_LOGIN_SERVER}/open-liberty-mp-azure-keyvault:latest  \
    --registry-server $ACR_LOGIN_SERVER \
    --registry-username $ACR_USER_NAME \
    --registry-password $ACR_PASSWORD \
    --user-assigned ${USER_ASSIGNED_IDENTITY_ID} \
    --env-vars \
        AZURE_CLIENT_ID=${USER_ASSIGNED_IDENTITY_CLIENT_ID} \
        AZURE_KEYVAULT_URL=${AZURE_KEYVAULT_URL} \
    --target-port 9080 \
    --ingress 'external'

Notitie

U wijst de door de gebruiker toegewezen beheerde identiteit toe aan het Container Apps-exemplaar met de parameter --user-assigned ${USER_ASSIGNED_IDENTITY_ID}.

Het Container Apps-exemplaar heeft toegang tot Azure Key Vault met twee omgevingsvariabelen die zijn opgegeven in de parameters --env-vars AZURE_CLIENT_ID=${USER_ASSIGNED_IDENTITY_CLIENT_ID} AZURE_KEYVAULT_URL=${AZURE_KEYVAULT_URL}. Vergeet niet dat de AZURE_KEYVAULT_URL omgevingsvariabele wordt geraadpleegd vanwege de omgevingsvariabelentoewijzingsregels die zijn gedefinieerd door de configuratiespecificatie van MicroProfile.

Haal vervolgens een volledig gekwalificeerde URL op voor toegang tot de app met behulp van de volgende opdracht:

export APP_URL=https://$(az containerapp show \
    --resource-group ${RESOURCE_GROUP_NAME} \
    --name ${ACA_NAME} \
    --query properties.configuration.ingress.fqdn \
    --output tsv)

Voer ten slotte de volgende opdrachten opnieuw uit om het voorbeeld te testen dat wordt uitgevoerd op het Container Apps-exemplaar:

# Get the value of secret "secret" stored in the Azure key vault. You should see 1234 in the response.
echo $(curl -s ${APP_URL}/config/value/secret -X GET)

# Get the value of secret "anotherSecret" stored in the Azure key vault. You should see 5678 in the response.
echo $(curl -s  ${APP_URL}/config/value/anotherSecret -X GET)

# Get the names of secrets stored in the Azure key vault. You should see ["anotherSecret","secret"] in the response.
echo $(curl -s  ${APP_URL}/config/propertyNames -X GET)

# Get the name-value paris of secrets stored in the Azure key vault. You should see {"anotherSecret":"5678","secret":"1234"} in the response.
echo $(curl -s  ${APP_URL}/config/properties -X GET)

U ziet nu de verwachte uitvoer die in de opmerkingen wordt beschreven. Als u ze niet ziet, kan de app nog steeds worden gestart. Wacht even en probeer het opnieuw.

Resources opschonen

Om Azure-kosten te vermijden, moet u overbodige resources opschonen. Wanneer de resources niet meer nodig zijn, voert u de volgende opdrachten uit om de resources op te schonen.

az keyvault delete \
    --resource-group "${RESOURCE_GROUP_NAME}" \
    --name "${KEY_VAULT_NAME}"

az keyvault purge \
    --name "${KEY_VAULT_NAME}" \
    --no-wait

az group delete \
    --name ${RESOURCE_GROUP_NAME} \
    --yes \
    --no-wait

Volgende stappen

Meer informatie vindt u in de volgende verwijzingen:

• Azure Container Apps
• Jakarta EE op Azure
• Azure-extensies voor MicroProfile
• MicroProfile
• Configuratiespecificatie van MicroProfile
• MicroProfile Config-API's
• Open Liberty
• Open Liberty Server-configuratie
• Liberty Maven Plugin
• Open Liberty Container Images