Metodtips för Helm-paket

Helm är en pakethanterare för Kubernetes som förenklar livscykelhanteringen för program. Helm-paket kallas diagram och består av YAML-konfigurations- och mallfiler. Vid körning av en Helm-åtgärd renderas diagrammen i Kubernetes-manifestfiler för att utlösa lämpliga programlivscykelåtgärder. För den mest effektiva integreringen med Azure Operator Service Manager följer du dessa rekommenderade metodtips när du utvecklar Helm-diagram.

Överväganden för registryPath och imagePullSecrets

Varje Helm chart kräver vanligtvis parametrarna registryPath och imagePullSecrets. Oftast exponerar du dessa parametrar i values.yaml filen. Inledningsvis var Azure Operator Service Manager beroende av att utgivarna hanterade dessa värden på ett strikt sätt (äldre metod), så att de kunde ersättas med rätt Azure-värden vid distribution. Men inte alla utgivare kan enkelt följa den strikta hanteringen av dessa värden. Vissa diagram döljer registryPath och/eller imagePullSecrets bakom villkor eller andra värdebegränsningar som inte alltid har uppfyllts. Vissa diagram deklarerar registryPath och/eller imagePullSecrets som en matris i stället för som den förväntade namngivna strängen.

För att minska efterlevnadskraven för utgivare introducerade Azure Operator Service Manager två förbättrade metoder: injectArtifactStoreDetail och klusterregistret. Dessa nyare metoder är inte beroende av att registryPath eller imagePullSecrets visas i Helm-paketet. I stället använder de här metoderna en webhook för att mata in rätt Azure-värden direkt i poddåtgärder.

Metodsammanfattning för registryPath och imagePullSecrets

Alla tre metoderna stöds för närvarande enligt beskrivningen i den här artikeln. Välj det bästa alternativet för din nätverksfunktion (NF) och användningsfall.

Legat:

  • Kräver att du parameteriserar registryPath och imagePullSecrets i Helm-värden och distributionsmallar för ersättning.
  • Är värd för avbildningar i Azure Container Registry.

InjectArtifactStoreDetail:

  • Använder en webhook för att mata in registryPath och imagePullSecrets direkt i poddåtgärder, med minimala beroenden på Helm.
  • Är värd för avbildningar i Azure Container Registry.

Klusterregister:

  • Använder en webhook för att injicera registryPath och imagePullSecrets direkt i poddoperationer, utan att vara beroende av Helm.
  • Är värd för avbildningar i NFO-tillägget (local network function operator).

I alla tre fallen ersätter Azure Operator Service Manager Azure-värden med de värden som du exponerar i mallar. Den enda skillnaden är substitutionsmetoden.

Äldre krav för registryPath och imagePullSecrets

Azure Operator Service Manager använder Azure Network Function Manager-tjänsten för att distribuera containerbaserade nätverksfunktioner (CNFs). Med den äldre metoden ersätter Azure Network Function Manager Azure Operator Service Manager-containerns registryPath och imagePullSecrets värden i Helm-åtgärden under distributionen av nätverksfunktioner.

Exempel på den äldre metoden

Följande Helm-distributionsmall visar ett exempel på hur du bör exponera registryPath och imagePullSecrets:

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

Följande values.yaml mall visar ett exempel på hur du kan ange registryPath värdena och imagePullSecrets :

global: 
   imagePullSecrets: [] 
   registryPath: ""

Följande values.schema.json fil visar ett exempel på hur du kan definiera registryPath värdena och imagePullSecrets :

{ 
  "$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" ], 
      } 
   } 
}

Följande nyttolast för nätverksfunktionsdefinitionsversion (NFDV) visar ett exempel på hur du kan ange registryPath värdena och imagePullSecrets vid distributionen:

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

I föregående exempel:

  • Värdet registryPath anges utan prefix, till exempel https:// eller oci://. Definiera vid behov ett prefix i Helm-paketet.
  • imagePullSecrets och registryPath måste tillhandahållas under NFDV-registrering.

Andra överväganden

Tänk på följande rekommendationer när du använder den äldre metoden.

Undvik referenser till ett externt register

Referenser till ett externt register kan orsaka valideringsproblem. Om deployment.yaml använder en hårdkodad registersökväg eller externa registerreferenser misslyckas valideringen.

Utföra manuella valideringar

Granska specifikationerna för avbildningarna och containrarna för att säkerställa att avbildningarna har prefixet registryPath och att imagePullSecrets är ifyllt med secretName:

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

Här är ett annat exempel:

 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>

Använda en lagringsplats och taggar för statiska avbildningar

Varje Helm-diagram ska innehålla en lagringsplats för statiska avbildningar och taggar. Du anger de statiska värdena via någon av följande metoder:

  • På raden image
  • I values.yaml, utan att visa dessa värden i NFDV

En NFDV ska mappas till en statisk uppsättning Helm-diagram och bilder. Du uppdaterar endast diagrammen och bilderna genom att publicera en ny NFDV, enligt följande exempel:

 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-krav för registryPath och imagePullSecrets

I vissa fall kanske Helm-diagram från tredje part inte är helt kompatibla med Azure Operator Service Manager-kraven för registryPath. I de här fallen kan du använda injectArtifactStoreDetails för att undvika att göra efterlevnadsändringar i Helm-paket.

Med injectArtifactStoreDetails aktiverad använder du en webhook-metod för att mata in rätt registryPath och imagePullSecrets dynamiskt under poddåtgärderna. Den här metoden åsidosätter de värden som har konfigurerats i Helm-paketet. Du måste fortfarande använda giltiga dummyvärden där registryPath och imagePullSecrets refereras, vanligtvis i avsnittet global i values.yaml.

I följande values.yaml exempel visas hur du kan ange registryPath värdena och imagePullSecrets för kompatibilitet med injectArtifactStoreDetails metoden:

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

Kommentar

Om registryPath lämnas tomt i det underliggande Helm-paketet misslyckas site network service (SNS)-driftsättningen vid nedladdning av avbildningen.

Använda metoden injectArtifactStoreDetails

Om du vill aktivera injectArtifactStoreDetailsanger du parametern installOptions i NF-resursens roleOverrides avsnitt till true, enligt följande exempel:

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

Kommentar

Helm-diagrampaketet måste fortfarande exponera korrekt formaterade registryPath värden och imagePullSecrets värden.

Klusterregisterkrav för registryPath och imagePullSecrets

Med ett klusterregister kopieras avbildningar från Azure Container Registry till en lokal Docker-lagringsplats i Nexus Kubernetes-klustret. Du använder en webhook-metod för att mata in rätt registryPath värden och imagePullSecrets värden dynamiskt under poddåtgärderna. Den här metoden åsidosätter de värden som har konfigurerats i Helm-paketet. Du måste fortfarande använda giltiga dummyvärden där registryPath och imagePullSecrets refereras, vanligtvis i avsnittet global i values.yaml.

I följande values.yaml exempel visas hur du kan ange registryPath värdena och imagePullSecrets för kompatibilitet med klusterregistrets metod:

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

Kommentar

Om registryPath lämnas tomt i det underliggande Helm-paketet, misslyckas SNS-driftsättningen vid nedladdning av imagen.

Mer information om hur du använder ett klusterregister finns i konceptdokumentationen.

Rekommendationer för oföränderlighetsbegränsningar

Oföränderlighetsbegränsningar förhindrar ändringar i en fil eller katalog. En oföränderlig fil kan till exempel inte ändras eller byta namn. Du bör undvika att använda föränderliga taggar som latest, develler stable. Om till exempel deployment.yaml använder latest för .Values.image.tag, misslyckas driftsättningen.

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

Rekommendationer för CRD-deklaration och användningsdelning

Vi rekommenderar att du delar upp deklarationen och användningen av kundresursdefinitioner i separata Helm-diagram för att stödja uppdateringar. Detaljerad information finns i Helm-dokumentationen om att avgränsa diagram.

Rekommendationer för versionsmärkning av avbildningar

För att säkerställa konsekventa och förutsägbara distributioner rekommenderar vi följande för alla containeravbildningar:

  • Undvik att använda :latest i produktionsmiljöer.
    • Användning av senaste kan orsaka oväntat beteende eftersom den faktiska bilden bakom den senaste kan ändras utan föregående meddelande.
    • Om taggvärdet ändras men taggnamnet förblir detsamma i en klusterregisterkonfiguration laddar klusterregistret inte ned den uppdaterade avbildningen igen.
    • Detta kan leda till användning av inaktuella eller inkonsekventa bilder.
  • Använd i stället alltid oföränderliga taggar som :1.4.2
  • Se till att varje bygge skapar en unik tagg, skriv inte över befintliga taggar.

Dessa metoder hjälper till att förhindra distributionsproblem och förbättra spårningsbarhet, återställningssäkerhet och säkerhetsefterlevnad.

Rekommendationer för sekventiell ordning i nfApplication

Som standard installeras eller uppdateras CNF-program baserat på i vilken ordning de visas i NFDV. För borttagningsåtgärden tas CNF-programmen bort i den angivna omvända ordningen. Om du behöver definiera en specifik ordning för CNF-program som skiljer sig från standardinställningen använder dependsOnProfile du för att definiera en unik sekvens för installation, uppdatering och borttagning.

Så här använder du dependsOnProfile

Du kan använda dependsOnProfile i NFDV för att styra sekvensen av Helm-körningar för CNF-program. I exemplet som följer:

  • Under en installationsåtgärd distribueras CNF-programmen i följande ordning: dummyApplication1, dummyApplication2, dummyApplication.
  • Under en uppdateringsåtgärd uppdateras CNF-programmen i följande ordning: dummyApplication2, dummyApplication1, dummyApplication.
  • Under en borttagningsåtgärd tas CNF-programmen bort i följande ordning: 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"
    }
}

Vanliga fel med dependsOnProfile

Om koden dependsOnProfile som anges i NFDV för närvarande är ogiltig misslyckas NF-åtgärden med ett verifieringsfel. Meddelandet för verifieringsfelet visas i åtgärdsstatusresursen och ser ut ungefär som i följande exempel:

 {
  "id": "/providers/Microsoft.HybridNetwork/locations/EASTUS2EUAP/operationStatuses/ca051ddf-c8bc-4cb2-945c-a292bf7b654b*C9B39996CFCD97AB3A121AE136ED47F67BB13946C573EF90628C47628BC5EF5F",
  "name": "ca051ddf-c8bc-4cb2-945c-a292bf7b654b*C9B39996CFCD97AB3A121AE136ED47F67BB13946C573EF90628C47628BC5EF5F",
  "resourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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."
  }
}

Metodtips för att införa Helm 4

Helm har varit standardpakethanterare för Kubernetes sedan den första versionen 2016. Dess utveckling har följt Kubernetes egen utveckling nära:

  • Helm v2 (2016–2019): Introducerade diagrambaserad programpaketering men förlitade sig på en komponent på serversidan (Tiller), som skapade säkerhets- och multitenancy-problem.
  • Helm v3 (2019–2025): Tog bort Tiller och övergår till en endast klientmodell med förbättrad säkerhet och användbarhet. Den här versionen blev branschstandard och ackumulerade inkrementella förbättringar samtidigt som bakåtkompatibiliteten bibehålls.

Efter nästan sex år av Helm v3 ackumulerade projektet tekniska skulder, arkitektoniska begränsningar och säkerhetsutmaningar som det inte kunde hantera utan att införa icke-bakåtkompatibla ändringar. Den här situationen ledde till lanseringen av Helm v4 i slutet av 2025.

Vad Helm 4 representerar

Helm 4 är en betydande arkitekturutveckling snarare än en inkrementell uppgradering. Dess främsta mål är att:

  • Anpassa till moderna Kubernetes-distributionsmönster
  • Ta bort äldre Helm v3-beteenden
  • Förbättra utökningsbarhet, underhåll och säkerhet

Viktiga ändringar som introduceras med Helm 4 är:

  • Server-Side Apply (SSA): Ersätter den äldre metoden för trevägssammanslagning och justerar distributioner med Kubernetes-inbyggda avstämningssemantik.
  • Omdesignat plugin-system: Introducerar en mer utökningsbar arkitektur, inklusive valfria WebAssembly-baserade plugin-program för förbättrad isolering och flexibilitet.
  • Förbättrad resursspårning: Använder nyare Kubernetes-statusmekanismer, till exempel kstatus, för att ge mer exakt rapportering av distributionstillstånd.
  • Intern modernisering: Tar bort tekniska skulder och lägger grunden för framtida innovation och prestandaförbättringar.

Det är viktigt att Helm 4 upprätthåller kompatibilitet med befintliga Helm v3-diagram, vilket gör det möjligt för organisationer att införa Helm 4 gradvis utan att kräva omedelbara ändringar i diagram eller distributionsartefakter.

Relevans för AOSM-utgivare

AOSM-teamet planerar att stödja Helm 4 via två viktiga milstolpar:

  • Först släpper AOSM-teamet en NFO-version som innehåller Helm 4.1.4 som körs i ett "kompatibilitetsläge". Det här läget bevarar Helm 3.18-beteendet, så att utgivare kan använda Helm 4 utan att ändra befintliga diagram eller artefakter.
    • Du kan förhandsgranska den här NFO-versionen i dag i UKSouth-labbet.
  • För det andra släpper AOSM-teamet en NFO-version som tar bort kompatibilitetsanpassningar och aktiverar fullständigt Helm 4-beteende. Utgivare kan anta den här versionen när de är klara och förstå att diagram- och artefaktändringar kan krävas.
    • AOSM-teamet planerar den här NFO-versionen för utgivartestning i Q4 CY2026.

Utgivare fortsätter att ha flexibilitet när de väljer Helm-beteende under NFO-installationen. NFO använder som standard "kompatibilitetsläge", samtidigt som det finns ett installationsalternativ för att aktivera fullständig Helm 4-funktionalitet. Den här funktionen är klusteromfattande, vilket innebär att alla distributioner i ett kluster måste använda samma Helm-driftläge.

Information om kompatibilitetsläge

Följande inställningar bevarar Helm 3-beteendet när du kör Helm 4 i "kompatibilitetsläge":

  • Striktare schemavalidering
    • Helm 4 introducerar striktare validering som avvisar Go-typade sektorer, till exempel []map[string]interface{}, när JSON-matriser verifieras. Det här beteendet kan orsaka fel när NFO matar in imagePullSecrets-värden.
    • NFO uppdaterar värdeinmatningslogik för att använda []-gränssnittet{} i stället och granskar liknande kodsökvägar för att säkerställa kompatibilitet.
  • Server-Side Apply (SSA) aktiverat som standard
    • Helm 4 verifierar renderade manifest mot klustrets OpenAPI-schema innan resurser tillämpas. Diagram som innehåller ogiltiga fältdefinitioner som Helm 3 tidigare tolererade kan misslyckas med valideringen.
    • Kompatibilitetsläget inaktiverar SSA under installations- och uppgraderingsåtgärder för att bevara Helm 3-beteendet.
  • Ny väntemodell
    • Helm 4 använder som standard en händelsedriven väntemodell som kräver watch-behörigheter i Kubernetes. Det här beteendet kan misslyckas i Nexus-kluster där nödvändiga RBAC-behörigheter inte är tillgängliga.
    • Kompatibilitetsläget låser väntbeteendet till LegacyStrategy, vilket bevarar Helm 3:s pollningssemantik.
  • Återskapa det borttagna
    • Helm 4 tar bort stöd för Upgrade.Recreate. Körningspåverkan förväntas vara låg, men kundkonfigurerade värden i CRD skulle annars inte längre ha någon effekt.
    • Kompatibilitetsläget bevarar CRD-fältet för bakåtkompatibilitet men ignorerar det vid körning av Helm 4-åtgärder.
  • Validering av schema mot metaschema
    • Helm 4 validerar values.schema.json mot JSON-schemametaschemat. Diagram som innehåller icke-kompatibla schemadefinitioner avvisas innan värdevalidering sker. Det här beteendet är känt för att påverka vissa utgivardiagram.
    • Kompatibilitetsläge ställer in SkipSchemaValidation=true vid installation och uppgradering.
  • Last updated on