Konfigurowanie usługi MicroProfile z usługą Azure Key Vault

W tym samouczku pokazano, jak skonfigurować aplikację MicroProfile w celu pobierania wpisów tajnych z usługi Azure Key Vault przy użyciu interfejsów API konfiguracji microProfile. Deweloperzy korzystają z otwartego standardowego interfejsu API konfiguracji mikroprofile na potrzeby pobierania i wstrzykiwania danych konfiguracji do swoich mikrousług.

Wymagania wstępne

• Subskrypcja platformy Azure; Jeśli nie masz jeszcze subskrypcji platformy Azure, możesz aktywować korzyści dla subskrybentów MSDN lub utworzyć bezpłatne konto.
• Interfejs wiersza polecenia platformy Azure dla środowisk przypominających system Unix. Ten artykuł wymaga tylko wariantu powłoki Bash interfejsu wiersza polecenia platformy Azure.
  • Bash

    Zainstaluj interfejs wiersza polecenia platformy Azure i zaloguj się interaktywnie za pomocą polecenia az login , aby zalogować się na platformie Azure przed użyciem DefaultAzureCredential w kodzie.

    az login
    

    Program PowerShell

    Aby uwierzytelnić się za pomocą programu Azure PowerShell, uruchom Connect-AzAccount polecenie cmdlet . Domyślnie, podobnie jak w przypadku interfejsu wiersza polecenia platformy Azure, Connect-AzAccount uruchamia domyślną przeglądarkę internetową w celu uwierzytelnienia konta użytkownika.

    Connect-AzAccount
    

    Visual Studio Code

    Jeśli używasz programu Visual Studio Code, możesz również zalogować się na platformie Azure przy użyciu rozszerzenia konta platformy Azure.
  • Ten artykuł wymaga co najmniej wersji 2.61.0 interfejsu wiersza polecenia platformy Azure. Jeśli używasz usługi Azure Cloud Shell, najnowsza wersja jest już zainstalowana.
• Usługa Azure Cloud Shell ma wstępnie zainstalowane wszystkie te wymagania wstępne. Aby uzyskać więcej informacji, zobacz Szybki start dotyczący usługi Azure Cloud Shell.
• Jeśli uruchamiasz polecenia w tym przewodniku lokalnie (zamiast korzystać z usługi Azure Cloud Shell), wykonaj następujące kroki:
  • Przygotuj maszynę lokalną z zainstalowanym systemem operacyjnym przypominającym system Unix (na przykład Ubuntu, macOS lub Podsystem Windows dla systemu Linux).
  • Zainstaluj implementację java SE w wersji 17 lub nowszej (na przykład kompilacja Microsoft OpenJDK).
  • Zainstaluj program Maven w wersji 3.9.8 lub nowszej.
  • Zainstaluj program cURL.

Łączenie konfiguracji programu MicroProfile z usługą Azure Key Vault

Przyjrzyjmy się możliwości łączenia usługi Azure Key Vault i interfejsu API konfiguracji microProfile. Oto fragment kodu pola w klasie, która jest oznaczona adnotacjami i @Inject @ConfigProperty. Określony name w adnotacji jest nazwą wpisu tajnego do wyszukania w usłudze Azure Key Vault, a element defaultValue jest używany, jeśli wpis tajny nie zostanie odnaleziony. Wartość wpisu tajnego przechowywana w usłudze Azure Key Vault lub wartość domyślna, jeśli taki wpis tajny nie istnieje, jest automatycznie wstrzykiwana do pola w czasie wykonywania. Wstrzykiwanie wartości właściwości w ten sposób zapewnia wiele korzyści. Na przykład nie trzeba już przekazywać wartości w konstruktorach i metodach ustawiania, a konfiguracja jest zewnętrzna z kodu. Jedną z najbardziej zaawansowanych zalet jest posiadanie oddzielnych zestawów wartości dla środowisk deweloperskich, testowych i prod.

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

Dostęp do konfiguracji microProfile jest również możliwy w sposób imperatywny, jak pokazano w poniższym przykładzie:

public class DemoClass {
    @Inject
    Config config;

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

W tym przykładzie użyto implementacji biblioteki Open Liberty microProfile. Aby uzyskać pełną listę zgodnych implementacji, zobacz MicroProfile Compatible Implementations (Implementacje zgodne z technologią MicroProfile). W przykładzie pokazano również, jak konteneryzować i uruchamiać aplikację na platformie Azure.

W tym przykładzie użyto rozszerzenia platformy Azure o niskim tarciu dla niestandardowej biblioteki ConfigSource usługi MicroProfile Key Vault. Aby uzyskać więcej informacji na temat tej biblioteki, zobacz plik README biblioteki.

Poniżej przedstawiono kroki wymagane do uruchomienia tego kodu na komputerze lokalnym, począwszy od utworzenia zasobu usługi Azure Key Vault.

Tworzenie zasobu usługi Azure Key Vault

Interfejs wiersza polecenia platformy Azure służy do tworzenia zasobu usługi Azure Key Vault i wypełniania go dwoma wpisami tajnymi.

Najpierw zaloguj się do platformy Azure i ustaw subskrypcję jako bieżącą aktywną subskrypcję.

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

Następnie utwórz grupę zasobów o unikatowej nazwie, na przykład mp-kv-rg-ejb010424.

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

Teraz utwórz zasób usługi Azure Key Vault o unikatowej nazwie (na przykład kvejb010424), dodaj dwa wpisy tajne i wyeksportuj identyfikator URI usługi Key Vault jako zmienną środowiskową.

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

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

Zmienna środowiskowa AZURE_KEYVAULT_URL jest wymagana do skonfigurowania biblioteki do późniejszej pracy z przykładem. Pozostaw terminal otwarty i użyj go do uruchamiania aplikacji lokalnie później.

I już! Teraz masz usługę Key Vault uruchomioną na platformie Azure z dwoma wpisami tajnymi. Teraz możesz sklonować przykładowe repozytorium i skonfigurować je do korzystania z tego zasobu w aplikacji.

Rozpoczynanie pracy lokalnie

Ten przykład jest oparty na przykładowej aplikacji dostępnej w usłudze GitHub. Przejdź do otwartego wcześniej terminalu i uruchom następujące polecenia, aby sklonować repozytorium i uruchomić aplikację lokalnie:

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

Jeśli zostanie wyświetlony komunikat o You are in 'detached HEAD' stateprogramie , ten komunikat jest bezpieczny do zignorowania.

Uwaga

Biblioteka używa domyślnych poświadczeń platformy Azure do uwierzytelniania na platformie Azure.

Ponieważ konto zostało uwierzytelnione za pośrednictwem polecenia interfejsu wiersza polecenia az login platformy Azure lokalnie, uwierzytelnia się za pomocą tego konta w DefaultAzureCredential celu uzyskania dostępu do usługi Azure Key Vault.

Poczekaj, aż zobaczysz dane wyjściowe podobne do The defaultServer server is ready to run a smarter planet. Otwórz nowy terminal i uruchom następujące polecenia, aby przetestować przykład:

# 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)

Powinny zostać wyświetlone oczekiwane dane wyjściowe opisane w komentarzach. Wróć do terminalu, w którym działa aplikacja. Naciśnij Ctrl + C, aby zatrzymać aplikację.

Badanie przykładowej aplikacji

Dowiedzmy się, jak działa konfiguracja microProfile ogólnie, a biblioteka Custom ConfigSource usługi MicroProfile Key Vault działa w szczególności.

Zależność biblioteki

Uwzględnij usługę MicroProfile Key Vault Custom ConfigSource w aplikacji z następującą zależnością narzędzia Maven:

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

Nawiązywanie połączenia z usługą Azure Key Vault

Biblioteka azure-microprofile-config-keyvault łączy aplikację z usługą Azure Key Vault bez wprowadzania żadnych bezpośrednich zależności od interfejsów API platformy Azure. Biblioteka udostępnia implementację interfejsu ConfigSource specyfikacji microProfile, który wie, jak odczytywać z usługi Azure Key Vault. Pozostała część implementacji konfiguracji MicroProfile jest udostępniana przez środowisko uruchomieniowe Open Liberty. Aby uzyskać link do specyfikacji, zobacz Następne kroki.

Biblioteka definiuje azure.keyvault.url właściwość konfiguracji, aby powiązać aplikację z określonym magazynem kluczy. Specyfikacja konfiguracji microProfile definiuje "Reguły mapowania zmiennych środowiskowych" dla sposobu odnajdywania wartości właściwości konfiguracji, takiej jak azure.keyvault.url, w czasie wykonywania. Jedna z tych reguł określa, że właściwości są konwertowane na zmienne środowiskowe. Właściwość azure.keyvault.url powoduje, że zmienna środowiskowa AZURE_KEYVAULT_URL jest konsultowana.

Kluczowe klasy w przykładowej aplikacji

Przeanalizujmy zasób REST, które wywołano poprzednie polecenia cURL. Ten zasób REST jest zdefiniowany w klasie ConfigResource.java w projekcie integration-tests/open-liberty-sample .

@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));
    }
}

Metoda getConfigValue() używa wprowadzonej Config implementacji, aby wyszukać wartość ze źródeł konfiguracji aplikacji. Wszystkie wyszukiwania wartości w implementacji są znajdowane za pomocą algorytmu Config wyszukiwania zdefiniowanego przez specyfikację konfiguracji microProfile. Biblioteka azure-microprofile-config-keyvault dodaje usługę Azure Key Vault jako źródło konfiguracji.

Metoda getConfigSource() unika algorytmu wyszukiwania i przechodzi bezpośrednio do AzureKeyVaultConfigSource właściwości, aby rozwiązać problem. Ta metoda jest używana przez getConfigPropertyNames() metody i getConfigProperties() .

Uruchamianie w usłudze Azure Container Apps

W tej sekcji skonfigurujesz konteneryzację aplikacji, skonfigurujesz tożsamość zarządzaną przypisaną przez użytkownika, aby uzyskać dostęp do usługi Azure Key Vault i wdrożysz konteneryzowaną aplikację w usłudze Azure Container Apps.

Wróć do terminalu, w którym uruchomiono aplikację lokalnie i użyj jej w tej sekcji.

Konfigurowanie usługi Azure Container Registry

Usługa Azure Container Registry służy do konteneryzowania aplikacji i przechowywania obrazu aplikacji.

Najpierw utwórz usługę Azure Container Registry o unikatowej nazwie, na przykład acrejb010424.

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

Poczekaj kilka minut po powrocie tego polecenia przed kontynuowaniem.

Konteneryzowanie aplikacji

Następnie konteneryzuj aplikację i wypchnij obraz aplikacji do usługi Azure Container Registry. Upewnij się, że jesteś w ścieżce przykładowej aplikacji, na przykład azure-microprofile/integration-tests/open-liberty-sample.

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

Powinny zostać wyświetlone dane wyjściowe kompilacji, które kończą się komunikatem podobnym do Run ID: ca1 was successful after 1m28s. Jeśli nie widzisz podobnego komunikatu, rozwiąż problem przed kontynuowaniem.

Użyj następujących poleceń, aby pobrać informacje o połączeniu wymagane do uzyskania dostępu do obrazu podczas wdrażania aplikacji w usłudze Azure Container Apps później.

export ACR_LOGIN_SERVER=$(az acr show \
    --name $ACR_NAME \
    --query 'loginServer' \
    --output tsv)

Konfigurowanie tożsamości zarządzanej przypisanej przez użytkownika

Jak wspomniano wcześniej, biblioteka używa domyślnych poświadczeń platformy Azure do uwierzytelniania na platformie Azure. Podczas wdrażania aplikacji w usłudze Azure Container Apps należy ustawić zmienną środowiskową, aby skonfigurować wartość AZURE_CLIENT_ID DefaultAzureCredential w celu uwierzytelnienia się jako tożsamości zarządzanej zdefiniowanej przez użytkownika, która ma uprawnienia dostępu do usługi Azure Key Vault i zostanie przypisana do usługi Azure Container Apps później.

Najpierw użyj następujących poleceń, aby utworzyć tożsamość zarządzaną przypisaną przez użytkownika o unikatowej nazwie, na przykład uamiejb010424. Aby uzyskać więcej informacji, zobacz Tworzenie tożsamości zarządzanej przypisanej przez użytkownika.

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

Następnie użyj następujących poleceń, aby przyznać mu uprawnienia do pobierania i wyświetlania wpisów tajnych z usługi Azure Key Vault. Aby uzyskać więcej informacji, zobacz Przypisywanie zasad dostępu.

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}"

Dane wyjściowe muszą zawierać następujący kod JSON, aby można je było traktować jako pomyślne:

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

Jeśli dane wyjściowe nie zawierają tego kodu JSON, przed kontynuowaniem rozwiąż problem i rozwiąż go.

Następnie użyj następujących poleceń, aby pobrać identyfikator i identyfikator klienta tożsamości zarządzanej przypisanej przez użytkownika, aby później można było przypisać ją do usługi Azure Container Apps w celu uzyskania dostępu do usługi 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

Wdrażanie aplikacji w usłudze Azure Container Apps

Aplikacja została skoeneryzowana i skonfigurowano tożsamość zarządzaną przypisaną przez użytkownika w celu uzyskania dostępu do usługi Azure Key Vault. Teraz możesz wdrożyć konteneryzowaną aplikację w usłudze Azure Container Apps.

Najpierw utwórz środowisko dla usługi Azure Container Apps. Środowisko w usłudze Azure Container Apps tworzy bezpieczną granicę wokół grupy aplikacji kontenera. Aplikacje kontenera wdrożone w tym samym środowisku są wdrażane w tej samej sieci wirtualnej i zapisują dzienniki w tym samym obszarze roboczym usługi Log Analytics. Użyj polecenia az containerapp env create, aby utworzyć środowisko o unikatowej nazwie (na przykład acaenvejb010424), jak pokazano w poniższym przykładzie:

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

Następnie użyj polecenia az containerapp create , aby utworzyć wystąpienie usługi Container Apps o unikatowej nazwie (na przykład acaappejb010424), aby uruchomić aplikację po ściągnięciu obrazu z rejestru kontenerów, jak pokazano w poniższym przykładzie:

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-identity system \
    --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'

Uwaga

Tożsamość zarządzana przypisana przez użytkownika jest przypisywana do wystąpienia usługi Container Apps przy użyciu parametru --user-assigned ${USER_ASSIGNED_IDENTITY_ID}.

Wystąpienie usługi Container Apps może uzyskać dostęp do usługi Azure Key Vault z dwiema zmiennymi środowiskowymi podanymi w parametrach --env-vars AZURE_CLIENT_ID=${USER_ASSIGNED_IDENTITY_CLIENT_ID} AZURE_KEYVAULT_URL=${AZURE_KEYVAULT_URL}. Pamiętaj, że zmienna AZURE_KEYVAULT_URL środowiskowa jest konsultowana ze względu na reguły mapowania zmiennych środowiskowych zdefiniowane przez specyfikację konfiguracji microProfile.

Następnie pobierz w pełni kwalifikowany adres URL, aby uzyskać dostęp do aplikacji przy użyciu następującego polecenia:

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

Na koniec ponownie uruchom następujące polecenia, aby przetestować przykład uruchomiony w wystąpieniu usługi Container Apps:

# 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)

Powinny zostać wyświetlone oczekiwane dane wyjściowe opisane w komentarzach. Jeśli ich nie widzisz, aplikacja nadal może być uruchamiana. Poczekaj chwilę i spróbuj ponownie.

Czyszczenie zasobów

Aby uniknąć opłat za platformę Azure, należy wyczyścić niepotrzebne zasoby. Gdy zasoby nie są już potrzebne, uruchom następujące polecenia, aby wyczyścić zasoby.

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

Następne kroki

Aby dowiedzieć się więcej, zapoznaj się z następującymi odwołaniami:

• Azure Container Apps
• Jakarta EE na platformie Azure
• Rozszerzenia platformy Azure dla programu MicroProfile
• MicroProfile
• Specyfikacja konfiguracji programu MicroProfile
• Interfejsy API konfiguracji programu MicroProfile
• Open Liberty
• Konfiguracja serwera Open Liberty Server
• Wtyczka Liberty Maven
• Otwieranie obrazów kontenera Liberty