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-diagram kräver registryPath vanligtvis och imagePullSecrets parametrar. Oftast exponerar du dessa parametrar i values.yaml filen. Först var Azure Operator Service Manager beroende av att utgivare som hanterar dessa värden på ett strikt sätt (äldre metod) skulle ersättas med rätt Azure-värden under distributionen. 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 registryPath av 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 mata in registryPath och imagePullSecrets direkt i poddåtgärder, utan 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 du till exempel använder en hårdkodad registersökväg eller externa registerreferenser misslyckas verifieringen.

Utföra manuella valideringar

Granska specifikationerna för avbildningar och containrar för att säkerställa att avbildningarna har ett prefix för registryPath och som imagePullSecrets fylls i 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 exponera 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 dessa fall kan du använda injectArtifactStoreDetails för att undvika att göra ändringar i Helm-paketens efterlevnad.

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 juridiska dummy-värden där registryPath och refereras, vanligtvis i imagePullSecrets avsnittet i globalvalues.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 SNS-distributionen (Site Network Service) under nedladdningen 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 juridiska dummy-värden där registryPath och refereras, vanligtvis i imagePullSecrets avsnittet i globalvalues.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-distributionen under nedladdningen av avbildningen.

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 deployment.yaml det till exempel används latest för .Values.image.tagmisslyckas distributionen.

 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 avbildningsversionstaggning

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 att inaktuella eller inkonsekventa bilder körs.
  • 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."
  }
}
  • Last updated on