Aanbevolen procedures voor Helm-pakketten

Helm is een pakketbeheerder voor Kubernetes die het levenscyclusbeheer van toepassingen vereenvoudigt. Helm-pakketten worden grafieken genoemd en bestaan uit YAML-configuratie- en sjabloonbestanden. Bij het uitvoeren van een Helm-bewerking worden de grafieken weergegeven in Kubernetes-manifestbestanden om de juiste acties voor de levenscyclus van toepassingen te activeren. Volg deze aanbevolen procedures bij het ontwikkelen van Helm-charts voor de meest efficiënte integratie met Azure Operator Service Manager.

Overwegingen voor registryPath en imagePullSecrets

Voor elke Helm-chart zijn over het algemeen de parameters registryPath en imagePullSecrets vereist. Meestal maakt u deze parameters beschikbaar in het values.yaml bestand. In het begin is Azure Operator Service Manager afhankelijk van uitgevers die deze waarden op een strikte manier beheren (verouderde benadering), die tijdens de implementatie moeten worden vervangen door de juiste Azure-waarden. Maar niet alle uitgevers kunnen gemakkelijk voldoen aan het strikte beheer van deze waarden. Sommige grafieken verbergen registryPath en/of imagePullSecrets achter voorwaarden of andere waardebeperkingen, die niet altijd werden voldaan. Sommige grafieken declareren registryPath en/of imagePullSecrets als een matrix in plaats van als de verwachte benoemde tekenreeks.

Om de nalevingsvereisten voor uitgevers te verminderen, heeft Azure Operator Service Manager twee verbeterde methoden geïntroduceerd: injectArtifactStoreDetail en clusterregister. Deze nieuwere methoden zijn niet afhankelijk van het voorkomen van registryPath of imagePullSecrets in het Helm-pakket. In plaats daarvan gebruiken deze methoden een webhook om de juiste Azure-waarden rechtstreeks in podbewerkingen te injecteren.

Methodeoverzicht voor registryPath en imagePullSecrets

Alle drie de methoden worden momenteel ondersteund, zoals beschreven in dit artikel. Kies de beste optie voor uw netwerkfunctie (NF) en use-case.

Nalatenschap:

  • Hiervoor moet u registryPath en imagePullSecrets parameteriseren in Helm-waarden en deploymentsjablonen voor vervanging.
  • Hiermee worden containerimages gehost in Azure Container Registry.

InjectArtifactStoreDetail:

  • Gebruikt een webhook om registryPath en imagePullSecrets rechtstreeks in podbewerkingen te injecteren, met minimale afhankelijkheid van Helm.
  • Hiermee worden containerimages gehost in Azure Container Registry.

Clusterregister:

  • Gebruikt een webhook om registryPath en imagePullSecrets rechtstreeks in podbewerkingen te injecteren, zonder afhankelijk te zijn van Helm.
  • Host installatiekopieën in de extensie voor de lokale netwerkfunctie-operator (NFO).

In alle drie de gevallen vervangt Azure Operator Service Manager de waarden die u in sjablonen beschikbaar stelt door Azure-waarden. Het enige verschil is de vervangingsmethode.

Verouderde vereisten voor registryPath en imagePullSecrets

Azure Operator Service Manager maakt gebruik van de Azure Network Function Manager-service om containernetwerkfuncties (CNF's) te implementeren. Met de verouderde methode vervangt Azure Network Function Manager de Azure Operator Service Manager-container registryPath en imagePullSecrets -waarden in de Helm-bewerking tijdens de implementatie van netwerkfuncties.

Voorbeeld van de verouderde methode

In het volgende Helm-deploymentsjabloon ziet u een voorbeeld van hoe u registryPath en imagePullSecrets moet blootstellen:

apiVersion: apps/v1 
kind: Deployment 
metadata: 
  name: nginx-deployment 
  labels: 
    app: nginx 
spec: 
  replicas: 3 
  selector: 
    matchLabels: 
      app: nginx 
  template: 
    metadata: 
      labels: 
        app: nginx 
    spec: 
      {{- if .Values.global.imagePullSecrets }} 
      imagePullSecrets: {{ toYaml .Values.global.imagePullSecrets | nindent 8 }} 
      {{- end }} 
      containers: 
      - name: contosoapp 
        image:{{ .Values.global.registryPath }}/contosoapp:1.14.2 
        ports: 
        - containerPort: 80

In de volgende values.yaml sjabloon ziet u een voorbeeld van hoe u de registryPath en imagePullSecrets waarden kunt opgeven:

global: 
   imagePullSecrets: [] 
   registryPath: ""

In het volgende values.schema.json bestand ziet u een voorbeeld van hoe u de registryPath en imagePullSecrets waarden kunt definiëren:

{ 
  "$schema": "http://json-schema.org/draft-07/schema#", 
  "title": "StarterSchema", 
  "type": "object", 
  "required": ["global"], 
  "properties": { 
      "global" : {
          "type": "object",
          "properties": {
              "registryPath": {"type": "string"}, 
              "imagePullSecrets": {"type": "string"}, 
          }
          "required": [ "registryPath", "imagePullSecrets" ], 
      } 
   } 
}

De volgende aanvraagpayload voor de versie van de netwerkfunctiedefinitie (NFDV) toont een voorbeeld van hoe u de waarden registryPath en imagePullSecrets tijdens de implementatie kunt opgeven:

"registryValuesPaths": [ "global.registryPath" ], 
"imagePullSecretsValuesPaths": [ "global.imagePullSecrets" ],

In de voorgaande voorbeelden:

  • De registryPath waarde wordt ingesteld zonder voorvoegsel zoals https:// of oci://. Definieer indien nodig een voorvoegsel in het Helm-pakket.
  • imagePullSecrets en registryPath moeten tijdens de NFDV-onboarding worden verstrekt.

Andere overwegingen

Houd rekening met de volgende aanbevelingen wanneer u de verouderde methode gebruikt.

Verwijzingen naar een extern register voorkomen

Verwijzingen naar een extern register kunnen validatieproblemen veroorzaken. Als u bijvoorbeeld deployment.yaml een in code vastgelegd registerpad of externe registerverwijzingen gebruikt, mislukt de validatie.

Handmatige validaties uitvoeren

Controleer de images en containerspecificaties om ervoor te zorgen dat de images de prefix registryPath hebben en dat imagePullSecrets is ingevuld met secretName:

 helm template --set "global.imagePullSecrets[0].name=<secretName>" --set "global.registry.url=<registryPath>" <release-name> <chart-name> --dry-run

Hier volgt nog een voorbeeld:

 helm install --set "global.imagePullSecrets[0].name=<secretName>" --set "global.registry.url=<registryPath>" <release-name> <chart-name> --dry-run
 kubectl create secret <secretName> regcred --docker-server=<registryPath> --dockerusername=<regusername> --docker-password=<regpassword>

Een repository voor statische images en tags gebruiken

Elke Helm-chart moet een statische imagerepository en statische tags bevatten. U stelt de statische waarden op een van de volgende manieren in:

  • In de image regel
  • In values.yaml, zonder deze waarden zichtbaar te maken in de NFDV

Een NFDV moet overeenkomen met een statische set Helm-charts en images. U werkt de grafieken en afbeeldingen alleen bij door een nieuwe NFDV te publiceren, zoals wordt weergegeven in de volgende voorbeelden:

 image: "{{ .Values.global.registryPath }}/contosoapp:1.14.2"

 image: "{{ .Values.global.registryPath }}/{{ .Values.image.repository }}:{{ .Values.image.tag}}"
 
YAML values.yaml
image:
  repository: contosoapp
  tag: 1.14.2

 image: http://myUrl/{{ .Values.image.repository }}:{{ .Values.image.tag}}

injectArtifactStoreDetails-vereisten voor registryPath en imagePullSecrets

In sommige gevallen zijn Helm-grafieken van derden mogelijk niet volledig compatibel met de Azure Operator Service Manager-vereisten voor registryPath. In dergelijke gevallen kunt u injectArtifactStoreDetails gebruiken om te voorkomen dat compliancewijzigingen in Helm-pakketten moeten worden aangebracht.

Met injectArtifactStoreDetails ingeschakeld gebruikt u een webhook om de juiste registryPath en imagePullSecrets dynamisch te injecteren tijdens podbewerkingen. Deze methode overschrijft de waarden die zijn geconfigureerd in het Helm-pakket. U moet nog steeds geldige fictieve waarden gebruiken op plaatsen waar naar registryPath en imagePullSecrets wordt verwezen, meestal in de global sectie van values.yaml.

In het volgende values.yaml voorbeeld ziet u hoe u de registryPath en imagePullSecrets waarden voor compatibiliteit met de injectArtifactStoreDetails methode kunt opgeven:

global: 
   registryPath: "azure.io"
   imagePullSecrets: ["abc123"]

Notitie

Als registryPath leeg blijft in het onderliggende Helm-pakket, mislukt de implementatie van de site network service (SNS) tijdens het downloaden van de containerimage.

De methode injectArtifactStoreDetails gebruiken

Om injectArtifactStoreDetails in te schakelen, stelt u de parameter installOptions in de sectie roleOverrides van de NF-resource in op true, zoals in het volgende voorbeeld:

resource networkFunction 'Microsoft.HybridNetwork/networkFunctions@2023-09-01' = {
  name: nfName
  location: location
  properties: {
    nfviType: 'AzureArcKubernetes'
    networkFunctionDefinitionVersionResourceReference: {
      id: nfdvId
      idType: 'Open'
    }
    allowSoftwareUpdate: true
    nfviId: nfviId
    deploymentValues: deploymentValues
    configurationType: 'Open'
    roleOverrideValues: [
      // Use inject artifact store details feature on test app 1
      '{"name":"testapp1", "deployParametersMappingRuleProfile":{"helmMappingRuleProfile":{"options":{"installOptions":{"atomic":"false","wait":"false","timeout":"60","injectArtifactStoreDetails":"true"},"upgradeOptions": {"atomic": "false", "wait": "true", "timeout": "100", "injectArtifactStoreDetails": "true"}}}}}'
    ]
  }
}

Notitie

Het Helm-chartpakket moet nog steeds correct opgemaakte waarden voor registryPath en imagePullSecrets bevatten.

Clusterregistervereisten voor registryPath en imagePullSecrets

Met een clusterregister worden installatiekopieën gekopieerd van Azure Container Registry naar een lokale Docker-opslagplaats in het Nexus Kubernetes-cluster. U gebruikt een webhookmethode om tijdens podbewerkingen dynamisch de juiste waarden registryPath en imagePullSecrets in te voegen. Deze methode overschrijft de waarden die zijn geconfigureerd in het Helm-pakket. U moet nog steeds geldige fictieve waarden gebruiken op plaatsen waar naar registryPath en imagePullSecrets wordt verwezen, meestal in de global sectie van values.yaml.

In het volgende values.yaml voorbeeld ziet u hoe u de registryPath en imagePullSecrets waarden voor compatibiliteit met de benadering van het clusterregister kunt opgeven:

global: 
   registryPath: "azure.io"
   imagePullSecrets: ["abc123"]

Notitie

Als registryPath leeg wordt gelaten in het onderliggende Helm-pakket, mislukt de SNS-implementatie tijdens het downloaden van de image.

Zie de conceptdocumentatie voor meer informatie over het gebruik van een clusterregister.

Aanbevelingen voor onveranderbaarheidsbeperkingen

Onveranderbaarheidsbeperkingen voorkomen wijzigingen in een bestand of map. Een onveranderbaar bestand kan bijvoorbeeld niet worden gewijzigd of hernoemd. Vermijd het gebruik van onveranderbare tags zoals latest, devof stable. Als deployment.yaml bijvoorbeeld latest gebruikt voor .Values.image.tag, mislukt de implementatie.

 image: "{{ .Values.global.registryPath }}/{{ .Values.image.repository }}:{{ .Values.image.tag}}"

Aanbevelingen voor CRD-declaratie en gebruikssplitsing

Het is raadzaam om de declaratie en het gebruik van resourcedefinities (CRD's) van klanten op te splitsen in afzonderlijke Helm-grafieken ter ondersteuning van updates. Zie de Helm-documentatie over het scheiden van grafieken voor gedetailleerde informatie.

Aanbevelingen voor versietagging van images

Om consistente en voorspelbare implementaties te garanderen, raden we het volgende aan voor alle containerinstallatiekopieën:

  • Vermijd het gebruik :latest in productieomgevingen.
    • Het gebruik van het meest recente kan onverwacht gedrag veroorzaken omdat de werkelijke afbeelding achter de meest recente wijziging zonder kennisgeving kan worden gewijzigd.
    • In een configuratie met een clusterregister geldt dat als de tagwaarde verandert maar de tagnaam hetzelfde blijft, het clusterregister de bijgewerkte image niet opnieuw downloadt.
    • Dit kan leiden tot het gebruik van verouderde of inconsistente images.
  • Gebruik in plaats daarvan altijd onveranderbare tags, zoals :1.4.2
  • Zorg ervoor dat elke build een unieke tag produceert, bestaande tags niet overschrijven.

Deze procedures helpen implementatieproblemen te voorkomen en traceerbaarheid, terugdraaiveiligheid en beveiligingsnaleving te verbeteren.

Aanbevelingen voor de volgorde van nfApplication

CNF-toepassingen worden standaard geïnstalleerd of bijgewerkt op basis van de volgorde waarin ze worden weergegeven in de NFDV. Voor de verwijderingsbewerking worden de CNF-toepassingen verwijderd in de opgegeven omgekeerde volgorde. Als u een specifieke volgorde van CNF-toepassingen wilt definiëren die afwijken van de standaardinstelling, gebruikt dependsOnProfile u om een unieke reeks te definiëren voor installatie-, update- en verwijderingsbewerkingen.

DependsOnProfile gebruiken

U kunt in de NFDV de volgorde van Helm-uitvoeringen voor CNF-toepassingen met dependsOnProfile beheren. In het volgende voorbeeld:

  • Tijdens een installatiebewerking worden de CNF-toepassingen in de volgende volgorde geïmplementeerd: dummyApplication1, dummyApplication2, dummyApplication.
  • Tijdens een updatebewerking worden de CNF-toepassingen in de volgende volgorde bijgewerkt: dummyApplication2, dummyApplication1, dummyApplication.
  • Tijdens een verwijderingsbewerking worden de CNF-toepassingen verwijderd in de volgende volgorde: dummyApplication2, dummyApplication1, dummyApplication.
{
    "location": "eastus",
    "properties": {
        "networkFunctionTemplate": {
            "networkFunctionApplications": [
                {
                  "dependsOnProfile": {
                        "installDependsOn": [
                            "dummyApplication1",
                            "dummyApplication2"
                        ],
                        "uninstallDependsOn": [
                            "dummyApplication1"
                        ],
                        "updateDependsOn": [
                            "dummyApplication1"
                        ]
                    },
                    "name": "dummyApplication"
                },
                {
                  "dependsOnProfile": {
                        "installDependsOn": [
                        ],
                        "uninstallDependsOn": [
                            "dummyApplication2"
                        ],
                        "updateDependsOn": [
                            "dummyApplication2"
                        ]
                    },
                    "name": "dummyApplication1"
                },
                {
                    "dependsOnProfile": null,
                    "name": "dummyApplication2"
                }
            ],
            "nfviType": "AzureArcKubernetes"
        },
        "networkFunctionType": "ContainerizedNetworkFunction"
    }
}

Veelvoorkomende fouten met dependsOnProfile

Momenteel, als de code die in de NFDV is verstrekt ongeldig is, mislukt de dependsOnProfile NF-bewerking met een validatiefout. Het bericht voor de validatiefout wordt weergegeven in de resource voor de bewerkingsstatus en ziet er ongeveer als volgt uit:

 {
  "id": "/providers/Microsoft.HybridNetwork/locations/EASTUS2EUAP/operationStatuses/ca051ddf-c8bc-4cb2-945c-a292bf7b654b*C9B39996CFCD97AB3A121AE136ED47F67BB13946C573EF90628C47628BC5EF5F",
  "name": "ca051ddf-c8bc-4cb2-945c-a292bf7b654b*C9B39996CFCD97AB3A121AE136ED47F67BB13946C573EF90628C47628BC5EF5F",
  "resourceId": "/subscriptions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/resourceGroups/xinrui-publisher/providers/Microsoft.HybridNetwork/networkfunctions/testnfDependsOn02",
  "status": "Failed",
  "startTime": "2023-07-17T20:48:01.4792943Z",
  "endTime": "2023-07-17T20:48:10.0191285Z",
  "error": {
    "code": "DependenciesValidationFailed",
    "message": "CyclicDependencies: Circular dependencies detected at hellotest."
  }
}

Aanbevolen werkwijzen voor de invoering van Helm 4

Helm is de standaardpakketbeheerder voor Kubernetes sinds de eerste release in 2016. De ontwikkeling ervan liep nauw parallel met die van Kubernetes zelf:

  • Helm v2 (2016-2019): Er is een op grafieken gebaseerde toepassingsverpakking geïntroduceerd, maar is gebaseerd op een component aan de serverzijde (Tiller), waardoor beveiligings- en multitenancyproblemen zijn ontstaan.
  • Helm v3 (2019-2025): Tiller is verwijderd en verplaatst naar een clientmodel met verbeterde beveiliging en bruikbaarheid. Deze versie werd de industriestandaard en verzamelde incrementele verbeteringen terwijl achterwaartse compatibiliteit behouden blijft.

Na bijna zes jaar Helm v3 heeft het project technische schulden, architecturale beperkingen en beveiligingsuitdagingen verzameld die niet konden worden aangepakt zonder wijzigingen die fouten veroorzaken. Deze situatie leidde tot de release van Helm v4 eind 2025.

Wat Helm 4 vertegenwoordigt

Helm 4 is een belangrijke architectuurontwikkeling in plaats van een incrementele upgrade. De belangrijkste doelstellingen zijn:

  • Uitlijnen op moderne Kubernetes-implementatiepatronen
  • Verouderde Helm v3-gedrag verwijderen
  • Uitbreidbaarheid, onderhoudbaarheid en beveiliging verbeteren

Belangrijke wijzigingen die zijn geïntroduceerd met Helm 4 zijn onder andere:

  • Server-Side Apply (SSA): vervangt de verouderde three-way-mergeaanpak en brengt deployments in lijn met de Kubernetes-native reconciliatiesemantiek.
  • Opnieuw ontworpen invoegtoepassingssysteem: introduceert een uitbreidbare architectuur, waaronder optionele webassembly-invoegtoepassingen voor verbeterde isolatie en flexibiliteit.
  • Verbeterde resourcetracking: maakt gebruik van nieuwere Kubernetes-statusmechanismen, zoals kstatus, om nauwkeurigere rapportage van implementatiestatussen te bieden.
  • Interne modernisering: verwijdert technische schulden en legt de basis voor toekomstige innovatie- en prestatieverbeteringen.

Belangrijk is dat Helm 4 compatibiliteit onderhoudt met bestaande Helm v3-grafieken, waardoor organisaties Helm 4 geleidelijk kunnen gebruiken zonder dat er onmiddellijke wijzigingen in grafieken of implementatieartefacten nodig zijn.

Relevantie voor AOSM-uitgevers

Het AOSM-team is van plan Helm 4 te ondersteunen via twee belangrijke mijlpalen:

  • Ten eerste publiceert het AOSM-team een NFO-versie met Helm 4.1.4 die in een 'compatibiliteitsmodus' werkt. In deze modus blijft het Helm 3.18-gedrag behouden, zodat uitgevers Helm 4 kunnen gebruiken zonder bestaande grafieken of artefacten te wijzigen.
    • U kunt deze NFO-versie vandaag testen in het UKSouth-lab.
  • Ten tweede brengt het AOSM-team een NFO-versie uit die compatibiliteitsaanpassingen verwijdert en volledig Helm 4-gedrag mogelijk maakt. Uitgevers kunnen deze versie gebruiken wanneer ze klaar zijn en begrijpen dat wijzigingen in grafieken en artefacten mogelijk vereist zijn.
    • Het AOSM-team heeft deze NFO-versie gepland voor tests door uitgevers in Q4 CY2026.

Uitgevers behouden flexibiliteit bij het kiezen van het gedrag van Helm tijdens de installatie van NFO. NFO wordt standaard ingesteld op de 'compatibiliteitsmodus', terwijl u een installatieoptie biedt om volledig Helm 4-gedrag in te schakelen. Deze mogelijkheid heeft een clusterbereik, wat betekent dat alle implementaties binnen een cluster dezelfde Helm-bedrijfsmodus moeten gebruiken.

Details van de compatibiliteitsmodus

De volgende instellingen behouden het Helm 3-gedrag bij het uitvoeren van Helm 4 in de 'compatibiliteitsmodus':

  • Strengere schemavalidatie
    • Helm 4 introduceert strengere validatie waarmee Go-getypte segmenten, zoals []map[string]interface{}, worden geweigerd bij het valideren van JSON-matrices. Dit gedrag kan fouten veroorzaken wanneer NFO imagePullSecrets-waarden injecteert.
    • NFO werkt waardeinjectielogica bij om in plaats daarvan []interface{} te gebruiken en controleert vergelijkbare codepaden om compatibiliteit te garanderen.
  • Server-Side Apply (SSA) is standaard ingeschakeld
    • Helm 4 valideert gerenderde manifesten op basis van het OpenAPI-clusterschema voordat resources worden toegepast. Grafieken met ongeldige velddefinities die Helm 3 eerder tolereerde, kunnen mislukken bij validatie.
    • De compatibiliteitsmodus schakelt SSA uit tijdens installatie- en upgradebewerkingen om het gedrag van Helm 3 te behouden.
  • Nieuw wachtmodel
    • Helm 4 is standaard ingesteld op een gebeurtenisgestuurd wachtmodel waarvoor Kubernetes-controlemachtigingen zijn vereist. Dit gedrag kan mislukken op Nexus-clusters waar de benodigde RBAC-machtigingen niet beschikbaar zijn.
    • De compatibiliteitsmodus zet het wachtgedrag vast op LegacyStrategy, waardoor de pollingsemantiek van Helm 3 behouden blijft.
  • Opnieuw maken
    • Helm 4 verwijdert ondersteuning voor Upgrade.Recreate. Hoewel de runtime-impact naar verwachting laag is, zouden door de klant geconfigureerde waarden in de CRD anders geen effect meer hebben.
    • De compatibiliteitsmodus behoudt het CRD-veld voor compatibiliteit met eerdere versies, maar negeert het bij het uitvoeren van Helm 4-bewerkingen.
  • Validatie van schemametaschema
    • Helm 4 valideert values.schema.json op basis van het JSON-schemametaschema. Grafieken met niet-compatibele schemadefinities worden geweigerd voordat waardenvalidatie plaatsvindt. Dit gedrag is bekend van invloed op sommige uitgeversgrafieken.
    • De compatibiliteitsmodus stelt SkipSchemaValidation=true in tijdens installatie- en upgradebewerkingen.
  • Laatst bijgewerkt om