Tutoriel : Test de validation automatisé

Dans le cadre de chaque validation qui génère des services de données avec Arc, Microsoft exécute des pipelines CI/CD automatisés qui effectuent des tests de bout en bout. Ces tests sont orchestrés via deux conteneurs qui sont conservés en même temps que le produit principal. Ces conteneurs sont les suivants :

• arc-ci-launcher : contenant des dépendances de déploiement (par exemple, des extensions CLI), ainsi que du code de déploiement de produit (à l’aide d’Azure CLI) pour les modes de connectivité directe et indirecte. Once Kubernetes is onboarded with the Data Controller, the container leverages Sonobuoy to trigger parallel integration tests.
• arc-sb-plugin: A Sonobuoy plugin containing Pytest-based end-to-end integration tests, ranging from simple smoke-tests (deployments, deletes), to complex high-availability scenarios, chaos-tests (resource deletions) etc.

Ces conteneurs de test sont mis publiquement à la disposition des clients et des partenaires pour effectuer des tests de validation des services de données avec Arc dans leurs propres clusters Kubernetes s’exécutant n’importe où, pour valider les éléments suivants :

• Kubernetes distro/versions
• Host disto/versions
• Stockage (StorageClass/CSI), mise en réseau (par exemple LoadBalancer, DNS)
• Autre configuration Kubernetes ou infrastructure spécifique

Pour les clients qui ont l’intention d’exécuter les services de données avec Arc sur une distribution non documentée, ils doivent exécuter ces tests de validation pour être considérés comme pris en charge. En outre, les partenaires peuvent utiliser cette approche pour certifier que leur solution est conforme aux services de données compatibles Arc - voir Validation Kubernetes des services de données avec Azure Arc.

Le diagramme suivant décrit ce processus de haut niveau :

Dans ce tutoriel, vous allez apprendre à :

Prerequisites

• Credentials:

  • Le fichier test.env.tmpl contient les informations d’identification nécessaires, et est une combinaison des pré-requis existants pour embarquer un Cluster connecté Azure Arc et un Contrôleur de données directement connecté. La configuration de ce fichier est expliquée ci-dessous avec des exemples.
  • A kubeconfig file to the tested Kubernetes cluster with cluster-admin access (required for Connected Cluster onboarding at this time)

• Client-tooling:

  • kubectl installé - version minimale (Majeure : « 1 », Mineure : « 21 »)
  • Interface de ligne de commande git (ou alternatives basées sur l’interface utilisateur)

Préparation du manifeste Kubernetes

The launcher is made available as part of the microsoft/azure_arc repository, as a Kustomize manifest - Kustomize is built into kubectl - so no additional tooling is required.

1. Clonez le référentiel localement :

git clone https://github.com/microsoft/azure_arc.git

2. Accédez à azure_arc/arc_data_services/test/launcher pour voir la structure de dossiers suivante :

├── base                                         <- Comon base for all Kubernetes Clusters
│   ├── configs
│   │   └── .test.env.tmpl                       <- To be converted into .test.env with credentials for a Kubernetes Secret
│   ├── kustomization.yaml                       <- Defines the generated resources as part of the launcher
│   └── launcher.yaml                            <- Defines the Kubernetes resources that make up the launcher
└── overlays                                     <- Overlays for specific Kubernetes Clusters
    ├── aks
    │   ├── configs
    │   │   └── patch.json.tmpl                  <- To be converted into patch.json, patch for Data Controller control.json
    │   └── kustomization.yaml
    ├── kubeadm
    │   ├── configs
    │   │   └── patch.json.tmpl
    │   └── kustomization.yaml
    └── openshift
        ├── configs
        │   └── patch.json.tmpl
        ├── kustomization.yaml
        └── scc.yaml

Dans ce tutoriel, nous allons nous concentrer sur les étapes pour AKS, mais la structure de superposition ci-dessus peut être étendue pour inclure des distributions Kubernetes supplémentaires.

Le manifeste prêt à être déployé représente les éléments suivants :

├── base
│   ├── configs
│   │   ├── .test.env                           <- Config 1: For Kubernetes secret, see sample below
│   │   └── .test.env.tmpl
│   ├── kustomization.yaml
│   └── launcher.yaml
└── overlays
    └── aks
        ├── configs
        │   ├── patch.json.tmpl
        │   └── patch.json                      <- Config 2: For control.json patching, see sample below
        └── kustomization.yam

Il y a deux fichiers qui doivent être générés pour localiser le lanceur à exécuter au sein d’un environnement spécifique. Chacun de ces fichiers peut être généré en collant et en remplissant chacun des fichiers de modèle (*.tmpl) ci-dessus :

• .test.env : remplir à partir de .test.env.tmpl
• patch.json : remplir à partir de patch.json.tmpl

Config 1 : .test.env

Un exemple complet du fichier .test.env, généré sur la base de .test.env.tmpl, est partagé avec un commentaire inline.

En d’autres termes, après avoir copié-collé .test.env.tmpl et l’avoir modifié pour créer .test.env, le fichier généré devrait ressembler à l’exemple ci-dessous. Le processus de remplissage du fichier .test.env est identique entre les systèmes d’exploitation et les terminaux.

Exemple terminé de .test.env :

# ======================================
# Arc Data Services deployment version =
# ======================================

# Controller deployment mode: direct, indirect
# For 'direct', the launcher will also onboard the Kubernetes Cluster to Azure Arc
# For 'indirect', the launcher will skip Azure Arc and extension onboarding, and proceed directly to Data Controller deployment - see `patch.json` file
export CONNECTIVITY_MODE="direct"

# The launcher supports deployment of both GA/pre-GA trains - see detailed explanation below [1]
export ARC_DATASERVICES_EXTENSION_RELEASE_TRAIN="stable"
export ARC_DATASERVICES_EXTENSION_VERSION_TAG="1.11.0"

# Image version
export DOCKER_IMAGE_POLICY="Always"
export DOCKER_REGISTRY="mcr.microsoft.com"
export DOCKER_REPOSITORY="arcdata"
export DOCKER_TAG="v1.11.0_2022-09-13"

# "arcdata" Azure CLI extension version override - see detailed explanation below [2]
export ARC_DATASERVICES_WHL_OVERRIDE=""

# ================
# ARM parameters =
# ================

# Custom Location Resource Provider Azure AD Object ID - this is a single, unique value per Azure AD tenant - see detailed explanation below [3]
export CUSTOM_LOCATION_OID="..."

# A pre-rexisting Resource Group is used if found with the same name. Otherwise, launcher will attempt to create a Resource Group
# with the name specified, using the Service Principal specified below (which will require `Owner/Contributor` at the Subscription level to work)
export LOCATION="eastus"
export RESOURCE_GROUP_NAME="..."

# A Service Principal with "sufficient" privileges - see detailed explanation below [4]
export SPN_CLIENT_ID="..."
export SPN_CLIENT_SECRET="..."
export SPN_TENANT_ID="..."
export SUBSCRIPTION_ID="..."

# Optional: certain integration tests test upload to Log Analytics workspace:
# https://learn.microsoft.com/azure/azure-arc/data/upload-logs
export WORKSPACE_ID="..."
export WORKSPACE_SHARED_KEY="..."

# ====================================
# Data Controller deployment profile =
# ====================================

# Samples for AKS
# To see full list of CONTROLLER_PROFILE, run: az arcdata dc config list
export CONTROLLER_PROFILE="azure-arc-aks-default-storage"

# azure, aws, gcp, onpremises, alibaba, other
export DEPLOYMENT_INFRASTRUCTURE="azure"

# The StorageClass used for PVCs created during the tests 
export KUBERNETES_STORAGECLASS="default"

# ==============================
# Launcher specific parameters =
# ==============================

# Log/test result upload from launcher container, via SAS URL - see detailed explanation below [5]
export LOGS_STORAGE_ACCOUNT="<your-storage-account>"
export LOGS_STORAGE_ACCOUNT_SAS="?sv=2021-06-08&ss=bfqt&srt=sco&sp=rwdlacupiytfx&se=...&spr=https&sig=..."
export LOGS_STORAGE_CONTAINER="arc-ci-launcher-1662513182"

# Test behavior parameters
# The test suites to execute - space seperated array, 
# Use these default values that run short smoke tests, further elaborate test suites will be added in upcoming releases
export SQL_HA_TEST_REPLICA_COUNT="3"
export TESTS_DIRECT="direct-crud direct-hydration controldb"
export TESTS_INDIRECT="billing controldb kube-rbac"
export TEST_REPEAT_COUNT="1"
export TEST_TYPE="ci"

# Control launcher behavior by setting to '1':
#
# - SKIP_PRECLEAN: Skips initial cleanup
# - SKIP_SETUP: Skips Arc Data deployment
# - SKIP_TEST: Skips sonobuoy tests
# - SKIP_POSTCLEAN: Skips final cleanup
# - SKIP_UPLOAD: Skips log upload
#
# See detailed explanation below [6]
export SKIP_PRECLEAN="0"
export SKIP_SETUP="0"
export SKIP_TEST="0"
export SKIP_POSTCLEAN="0"
export SKIP_UPLOAD="0"

Explication détaillée de certaines variables

1. ARC_DATASERVICES_EXTENSION_* - Version d’extension et train de mise en production

Obligatoire : requis pour les déploiements en mode direct.

Le lanceur peut déployer à la fois des versions de disponibilité générale et de pré-disponibilité générale.

La version d’extension pour le mappage de train de mise en production (ARC_DATASERVICES_EXTENSION_RELEASE_TRAIN) s’obtient ici :

• GA: stable - Version log
• Pre-GA: preview - Pre-release testing

2. ARC_DATASERVICES_WHL_OVERRIDE - URL de téléchargement de la version précédente d’Azure CLI

Facultatif : laissez cette valeur vide dans .test.env pour utiliser la valeur par défaut pré-empaquetée.

L’image de lanceur est pré-empaquetée avec la dernière version de l’interface CLI arcdata au moment de chaque publication d’image conteneur. However, to work with older releases and upgrade testing, it may be necessary to provide the launcher with Azure CLI Blob URL download link, to override the pre-packaged version; e.g to instruct the launcher to install version 1.4.3, fill in:

export ARC_DATASERVICES_WHL_OVERRIDE="https://azurearcdatacli.blob.core.windows.net/cli-extensions/arcdata-1.4.3-py2.py3-none-any.whl"

The CLI version to Blob URL mapping can be found here.

3. CUSTOM_LOCATION_OID - ID d’objet d’emplacements personnalisés à partir de votre locataire Microsoft Entra spécifique

Obligatoire : obligatoire pour la création de l’emplacement personnalisé du cluster connecté.

Les étapes suivantes proviennent d’Activer les emplacements personnalisés sur votre cluster pour récupérer l’identifiant unique de l’objet d’emplacement personnalisé pour votre locataire Microsoft Entra.

Il existe deux approches pour obtenir le CUSTOM_LOCATION_OID pour votre locataire Microsoft Entra.

1. Via Azure CLI :

   az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query objectId -o tsv
   # 51dfe1e8-70c6-4de...      <--- This is for Microsoft's own tenant - do not use, the value for your tenant will be different, use that instead to align with the Service Principal for launcher.
   

   

2. Via le portail Azure - accédez à votre panneau Microsoft Entra et recherchez Custom Locations RP :

   

4. SPN_CLIENT_* - Informations d’identification du principal du service

Obligatoire : obligatoire pour les déploiements en mode direct.

Le lanceur se connecte à Azure à l’aide de ces informations d’identification.

Les tests de validation doivent être effectués sur un cluster Kubernetes et des abonnements Azure de non-production/de test en se concentrant sur la validation fonctionnelle de Kubernetes et de la configuration de l’infrastructure. Par conséquent, pour éviter les étapes manuelles requises pour effectuer les lancements, il est recommandé de fournir un SPN_CLIENT_ID/SECRET qui a Owner au niveau du groupe de ressources (ou de l’abonnement), car cela créera plusieurs ressources dans ce groupe de ressources, et attribuera des autorisations à ces ressources par rapport à plusieurs identités managées créées dans le cadre du déploiement (ces attributions de rôles nécessitent à leur tour que le principal du service ait Owner).

5. LOGS_STORAGE_ACCOUNT_SAS - URL SAS du compte de stockage Blob

Recommandé : laisser cette valeur vide signifie que vous n’obtiendrez pas les résultats et journaux de test.

The launcher needs a persistent location (Azure Blob Storage) to upload results to, as Kubernetes doesn't (yet) allow copying files from stopped/completed pods - see here. Le lanceur réussit à se connecter à Stockage Blob Azure à l’aide d’une URL SAS à portée de compte (par opposition à une portée de conteneur ou blob), une URL signée avec une définition d’accès limitée dans le temps (voir Accorder un accès limité aux ressources du Stockage Azure à l’aide des signatures d’accès partagé (SAP)), afin de :

1. Créer un conteneur de stockage dans le compte de stockage pré-existant (LOGS_STORAGE_ACCOUNT), s’il n’existe pas (nom basé sur LOGS_STORAGE_CONTAINER)
2. Créer des objets blob nommés de manière unique (fichiers tar de journal de test)

Les étapes proviennent de l’article Accorder un accès limité aux ressources du Stockage Azure à l’aide des signatures d’accès partagé (SAS).

?sv=2021-06-08&ss=bfqt&srt=sco&sp=rwdlacupiytfx&se=...&spr=https&sig=...

Il existe plusieurs approches pour générer une URL SAP. Cet exemple montre le portail :

Pour utiliser Azure CLI à la place, consultez az storage account generate-sas

6. SKIP_* - Contrôler le comportement du lanceur en ignorant certaines étapes

Facultatif : laissez vide dans .test.env pour exécuter toutes les étapes (équivalentes à 0 ou vides)

Le lanceur expose des variables SKIP_* pour exécuter et ignorer des étapes spécifiques, par exemple, pour effectuer une exécution « nettoyage uniquement ».

Bien que le lanceur soit conçu pour faire le ménage au début et à la fin de chaque exécution, il est possible que des échecs de lancement et/ou de test laissent des résidus de ressources derrière eux. Pour exécuter le lanceur en mode « nettoyage uniquement », définissez les variables suivantes dans .test.env :

export SKIP_PRECLEAN="0"         # Run cleanup
export SKIP_SETUP="1"            # Do not setup Arc-enabled Data Services
export SKIP_TEST="1"             # Do not run integration tests
export SKIP_POSTCLEAN="1"        # POSTCLEAN is identical to PRECLEAN, although idempotent, not needed here
export SKIP_UPLOAD="1"           # Do not upload logs from this run

Les paramètres ci-dessus indiquent au lanceur de nettoyer toutes les ressources Arc et Arc Data Services, et de ne pas déployer/tester/charger les journaux.

Config 2 : patch.json

Un exemple complet du fichier patch.json, généré sur la base de patch.json.tmpl, est partagé ci-dessous :

Notez que le spec.docker.registry, repository, imageTag doit être identique aux valeurs dans .test.env ci-dessus

Exemple terminé de patch.json :

{
    "patch": [
        {
            "op": "add",
            "path": "spec.docker",
            "value": {
                "registry": "mcr.microsoft.com",
                "repository": "arcdata",
                "imageTag": "v1.11.0_2022-09-13",
                "imagePullPolicy": "Always"
            }
        },        
        {
            "op": "add",
            "path": "spec.storage.data.className",
            "value": "default"
        },  
        {
            "op": "add",
            "path": "spec.storage.logs.className",
            "value": "default"
        }                  
    ]
}

Launcher deployment

It is recommended to deploy the launcher in a Non-Production/Test cluster - as it performs destructive actions on Arc and other used Kubernetes resources.

Spécification imageTag

Le lanceur est défini dans le manifeste Kubernetes comme un Job, ce qui nécessite d’indiquer à Kubernetes où trouver l’image du lanceur. Vous définissez cela dans base/kustomization.yaml :

images:
- name: arc-ci-launcher
  newName: mcr.microsoft.com/arcdata/arc-ci-launcher
  newTag: v1.11.0_2022-09-13

kubectl apply

Pour vérifier que le manifeste a été correctement configuré, essayez la validation côté client avec --dry-run=client, qui imprime les ressources Kubernetes à créer pour le lanceur :

kubectl apply -k arc_data_services/test/launcher/overlays/aks --dry-run=client
# namespace/arc-ci-launcher created (dry run)
# serviceaccount/arc-ci-launcher created (dry run)
# clusterrolebinding.rbac.authorization.k8s.io/arc-ci-launcher created (dry run)
# secret/test-env-fdgfm8gtb5 created (dry run)                                        <- Created from Config 1: `patch.json`
# configmap/control-patch-2hhhgk847m created (dry run)                                <- Created from Config 2: `.test.env`
# job.batch/arc-ci-launcher created (dry run)

Pour déployer le lanceur et les journaux, exécutez ce qui suit :

kubectl apply -k arc_data_services/test/launcher/overlays/aks
kubectl wait --for=condition=Ready --timeout=360s pod -l job-name=arc-ci-launcher -n arc-ci-launcher
kubectl logs job/arc-ci-launcher -n arc-ci-launcher --follow

À ce stade, le lanceur doit démarrer et vous devriez voir les éléments suivants :

Bien qu’il soit préférable de déployer le lanceur dans un cluster sans ressources Arc préexistantes, le lanceur contient une validation préliminaire pour découvrir les CRD et les ressources ARM Arc et Arc Data Services préexistants, et tente de les nettoyer au mieux (en utilisant les informations d’identification de principal de service fournies), avant de déployer la nouvelle version :

Ce même processus de découverte et de nettoyage des métadonnées est également exécuté lors de la sortie du lanceur, pour laisser le cluster aussi proche que possible de son état pré-existant avant le lancement.

Étapes effectuées par le lanceur

À un niveau élevé, le lanceur effectue la séquence d’étapes suivante :

1. S’authentifier auprès de l’API Kubernetes à l’aide d’un compte de service monté sur pod

2. S’authentifier auprès de l’API ARM à l’aide du principal de service monté par secret

3. Effectuer une analyse des métadonnées CRD pour découvrir les ressources personnalisées Arc et Arc Data Services existantes

4. Nettoyer toutes les ressources personnalisées existantes dans Kubernetes et les ressources suivantes dans Azure. En cas d’incompatibilité entre les informations d’identification dans .test.env par rapport aux ressources existantes dans le cluster, quitter.

5. Générer un ensemble unique de variables d’environnement en fonction du nom du cluster Arc, du contrôleur de données et de l’emplacement/espace de noms personnalisé. Imprime les variables d’environnement, en dissimulant les valeurs sensibles (par exemple, mot de passe du principal de service, etc.)

6. a. Pour le mode direct : intégrez le cluster à Azure Arc, puis déployez le contrôleur.

   b. Pour le mode indirect : déployer le contrôleur de données

7. Une fois que le contrôleur de données est Ready, générez un ensemble de journaux Azure CLI (az arcdata dc debug) et stockez-le localement, étiqueté setup-complete, comme base de référence.

8. Utilisez la variable d’environnement TESTS_DIRECT/INDIRECT à partir de .test.env pour lancer une série de tests Sonobuoy parallélisés en fonction d’un tableau séparé par des espaces (TESTS_(IN)DIRECT). Ces exécutions s’exécutent dans un nouvel espace de noms sonobuoy, à l’aide du pod arc-sb-plugin qui contient les tests de validation Pytest.

9. Sonobuoy aggregator accumulate the junit test results and logs per arc-sb-plugin test run, which are exported into the launcher pod.

10. Retournez le code de sortie des tests et générez un autre ensemble de journaux de débogage - Azure CLI et sonobuoy - stockés localement, étiquetés comme test-complete.

11. Effectuer une analyse des métadonnées CRD, comme à l’étape 3, pour découvrir les ressources personnalisées Arc et Arc Data Services existantes. Ensuite, passez à la destruction de toutes les ressources Arc et Arc Data dans l’ordre inverse à partir du déploiement, ainsi que des CRD, Role/ClusterRoles, PV/PVC, etc.

12. Attempt to use the SAS token LOGS_STORAGE_ACCOUNT_SAS provided to create a new Storage Account container named based on LOGS_STORAGE_CONTAINER, in the pre-existing Storage Account LOGS_STORAGE_ACCOUNT. Si le conteneur de compte de stockage existe déjà, utilisez-le. Chargez tous les résultats et journaux de test locaux dans ce conteneur de stockage en tant que tarball (voir ci-dessous).

13. Exit.

Tests effectués par suite de tests

There are approximately 375 unique integration tests available, across 27 test suites - each testing a separate functionality.

Par exemple, pour sqlinstance-ha, les tests suivants sont effectués :

• test_critical_configmaps_present : garantit que les ConfigMaps et les champs pertinents sont présents pour une instance SQL.
• test_suspended_system_dbs_auto_heal_by_orchestrator : garantit que master et msdb sont suspendus par un moyen (dans ce cas, utilisateur). La maintenance d’Orchestrator réconcilie le rétablissement automatique.
• test_suspended_user_db_does_not_auto_heal_by_orchestrator : garantit que si une base de données utilisateur est délibérément suspendue par l’utilisateur, la maintenance d’Orchestrator ne réconcilie pas le rétablissement automatique.
• test_delete_active_orchestrator_twice_and_delete_primary_pod : supprime le pod d’orchestrateur plusieurs fois, suivi du réplica principal et vérifie que tous les réplicas sont synchronisés. Les attentes de temps de basculement pour 2 réplica sont assouplies.
• test_delete_primary_pod: supprime les réplica primaires et vérifie que tous les réplicas sont synchronisés. Les attentes de temps de basculement pour 2 réplica sont assouplies.
• test_delete_primary_and_orchestrator_pod : supprime le réplica primaire et le pod orchestrateur et vérifie que tous les réplicas sont synchronisés.
• test_delete_primary_and_controller : Supprime le réplica primaire et le pod du contrôleur de données, vérifie que le point de terminaison primaire est accessible et que le nouveau réplica primaire est synchronisé. Les attentes de temps de basculement pour 2 réplica sont assouplies.
• test_delete_one_secondary_pod: supprime le réplica secondaire et le pod du contrôleur de données et vérifie que tous les réplicas sont synchronisés.
• test_delete_two_secondaries_pods: supprime les réplicas secondaires et le pod du contrôleur de données et vérifie que tous les réplicas sont synchronisés.
• test_delete_controller_orchestrator_secondary_replica_pods:
• test_failaway : force le basculement du groupe de disponibilité en dehors du primaire actuel, garantit que le nouveau groupe de disponibilité n’est pas le même que l’ancien. Vérifie que tous les réplicas sont synchronisés.
• test_update_while_rebooting_all_non_primary_replicas : teste les mises à jour pilotées par le contrôleur sont résistantes avec des tentatives en dépit de diverses circonstances turbulentes.

Examen des résultats des tests

Un exemple de conteneur de stockage et de fichier chargé par le lanceur :

Et les résultats des tests générés à partir de l’exécution :

Nettoyer les ressources

Pour supprimer le lanceur, exécutez :

kubectl delete -k arc_data_services/test/launcher/overlays/aks

Cela nettoie les manifestes de ressources déployés dans le cadre du lanceur.

Related content