Freigeben über

Bewährte Methoden für das Helm-Paket

Helm ist ein Paketmanager für Kubernetes, der die Verwaltung des Anwendungslebenszyklus vereinfacht. Helmpakete werden als Diagramme bezeichnet und bestehen aus YAML-Konfigurations- und Vorlagendateien. Bei Ausführung eines Helm-Vorgangs werden die Diagramme in Kubernetes-Manifestdateien gerendert, um die entsprechenden Anwendungslebenszyklusaktionen auszulösen. Befolgen Sie bei der Entwicklung von Helm-Diagrammen diese empfohlenen bewährten Methoden, um die effizienteste Integration in Azure Operator Service Manager zu erzielen.

Überlegungen zu registryPath und imagePullSecrets

Im Allgemeinen erfordert jedes Helm-Chart die Parameter registryPath und imagePullSecrets. Am häufigsten machen Sie diese Parameter in der values.yaml Datei verfügbar. Zunächst hängt azure Operator Service Manager von Publishern ab, die diese Werte streng verwalten (Legacy-Ansatz), um während der Bereitstellung durch die richtigen Azure-Werte ersetzt zu werden. Aber nicht alle Verlage konnten die strikte Verwaltung dieser Werte leicht einhalten. Einige Diagramme blenden registryPath und/oder imagePullSecrets durch Bedingungen oder andere Wertbeschränkungen aus, die nicht immer erfüllt wurden. Einige Diagramme deklarieren registryPath und/oder imagePullSecrets als Array anstelle der erwarteten benannten Zeichenfolge.

Um die Complianceanforderungen für Herausgeber zu verringern, führte Azure Operator Service Manager zwei verbesserte Methoden ein: injectArtifactStoreDetail und die Clusterregistrierung. Diese neueren Methoden hängen nicht davon ab, das registryPath oder imagePullSecrets im Helm-Paket vorhanden sind. Stattdessen verwenden diese Methoden einen Webhook, um die richtigen Azure-Werte direkt in Pod-Vorgänge einzufügen.

Methodenzusammenfassung für registryPath und imagePullSecrets

Alle drei Methoden werden derzeit unterstützt, wie in diesem Artikel beschrieben. Wählen Sie die beste Option für Ihre Netzwerkfunktion (NF) und den Anwendungsfall aus.

Hinterlassenschaft:

  • Erfordert, dass Sie registryPath und imagePullSecrets in Helm-Werten und Bereitstellungsvorlagen für die Ersetzung parametrisieren.
  • Hosten von Images in der Azure-Containerregistrierung.

InjectArtifactStoreDetail:

  • Verwendet einen Webhook, um registryPath und imagePullSecrets mit minimalen Abhängigkeiten von Helm direkt in Podvorgänge zu injizieren.
  • Hosten von Images in der Azure-Containerregistrierung.

Clusterregistrierung:

  • Verwendet einen Webhook, um registryPath und imagePullSecrets ohne Abhängigkeiten von Helm direkt in Podvorgänge zu injizieren.
  • Hostet Images in der lokalen NFO-Erweiterung (Network Function Operator).

In allen drei Fällen ersetzt Azure Operator Service Manager Azure-Werte für alle Werte, die Sie in Vorlagen verfügbar machen. Der einzige Unterschied ist die Methode der Ersetzung.

Legacyanforderungen für registryPath und imagePullSecrets

Azure Operator Service Manager verwendet den Azure Network Function Manager-Dienst, um containerisierte Netzwerkfunktionen (CNFs) bereitzustellen. Mit der Legacymethode ersetzt der Azure-Netzwerkfunktionsmanager die Werte registryPath und imagePullSecrets des Azure Operator Service Manager-Containers während der Bereitstellung von Netzwerkfunktionen im Helm-Vorgang.

Beispiel für die veraltete Methode

Die folgende Helm-Bereitstellungsvorlage zeigt ein Beispiel dafür, wie Sie registryPath und imagePullSecrets verfügbar machen sollten:

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

Die folgende values.yaml Vorlage zeigt ein Beispiel dafür, wie Sie die Werte registryPath und imagePullSecrets bereitstellen können.

global: 
   imagePullSecrets: [] 
   registryPath: ""

Die folgende values.schema.json Datei zeigt ein Beispiel dafür, wie Sie die Werte registryPath und imagePullSecrets definieren können.

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

Die folgende Anforderungsnutzlast der Netzwerkfunktionsdefinitionsversion (NFDV) zeigt ein Beispiel dafür, wie Sie die registryPath- und imagePullSecrets-Werte bei der Bereitstellung angeben können.

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

In den vorherigen Beispielen:

  • Der registryPath Wert wird ohne Präfix wie https:// oder oci:// gesetzt. Definieren Sie bei Bedarf ein Präfix im Helm-Paket.
  • imagePullSecrets und registryPath müssen während des NFDV-Onboardings bereitgestellt werden.

Weitere Überlegungen

Berücksichtigen Sie die folgenden Empfehlungen, wenn Sie die Legacymethode verwenden.

Vermeiden von Verweisen auf eine externe Registrierung

Verweise auf eine externe Registrierung können Zu Überprüfungsproblemen führen. Wenn deployment.yaml z. B. einen hartcodierten Registrierungspfad oder externe Registrierungsverweise verwendet, schlägt die Validierung fehl.

Durchführen manueller Überprüfungen

Überprüfen Sie die Images und Containerspezifikationen, um sicherzustellen, dass die Images ein Präfix von registryPath haben und imagePullSecrets mit secretName gefüllt ist.

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

Hier ist ein weiteres Beispiel angegeben:

 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>

Verwenden eines statischen Bild-Repositorys und Tags

Jeder Helm-Chart sollte ein statisches Imagerepository und Tags enthalten. Sie legen die statischen Werte über eine der folgenden Methoden fest:

  • In der image Zeile
  • In values.yaml, ohne diese Werte im NFDV offenzulegen

Ein NFDV sollte einem statischen Satz von Helm-Charts und Images zugeordnet werden. Sie aktualisieren die Diagramme und Bilder nur, indem Sie einen neuen NFDV veröffentlichen, wie in den folgenden Beispielen gezeigt:

 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-Anforderungen für registryPath und imagePullSecrets

In einigen Fällen sind Helm-Charts von Drittanbietern möglicherweise nicht vollständig mit den Anforderungen von Azure Operator Service Manager für registryPath kompatibel. In diesen Fällen können Sie injectArtifactStoreDetails verwenden, um Compliance-Änderungen an Helm-Paketen zu vermeiden.

Aktivieren Sie injectArtifactStoreDetails, und verwenden Sie eine Webhookmethode, um die entsprechenden Werte für registryPath und imagePullSecrets dynamisch während der Podvorgänge zu injizieren. Diese Methode setzt die Werte außer Kraft, die im Helm-Paket konfiguriert sind. Sie müssen immer noch legale Dummywerte verwenden, an denen registryPath und imagePullSecrets referenziert werden, meist im global-Abschnitt von values.yaml.

Das folgende values.yaml Beispiel zeigt, wie Sie die registryPath- und imagePullSecrets-Werte für die Kompatibilität mit dem injectArtifactStoreDetails-Ansatz bereitstellen können.

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

Hinweis

Wenn registryPath im zugrunde liegenden Helm-Paket leer bleibt, tritt bei der SNS-Bereitstellung (Site Network Service, Standortnetzwerkdienst) während des Imagedownloads ein Fehler auf.

Verwenden der injectArtifactStoreDetails-Methode

Legen Sie zum Aktivieren von injectArtifactStoreDetails den installOptions Parameter im Abschnitt roleOverrides der NF-Ressource auf true fest, wie im folgenden Beispiel gezeigt:

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

Hinweis

Das Helm-Chart-Paket muss weiterhin ordnungsgemäß formatierte registryPath- und imagePullSecrets-Werte verfügbar machen.

Clusterregistrierungsanforderungen für registryPath und imagePullSecrets

Bei einer Clusterregistrierung werden Bilder aus der Azure-Containerregistrierung in ein lokales Docker-Repository im Nexus Kubernetes-Cluster kopiert. Sie verwenden eine Webhook-Methode, um die richtigen registryPath- und imagePullSecrets-Werte während der Pod-Vorgänge dynamisch einzufügen. Diese Methode setzt die Werte außer Kraft, die im Helm-Paket konfiguriert sind. Sie müssen immer noch legale Dummywerte verwenden, an denen registryPath und imagePullSecrets referenziert werden, meist im global-Abschnitt von values.yaml.

Das folgende values.yaml Beispiel zeigt, wie Sie die Werte registryPath und imagePullSecrets für die Kompatibilität mit dem Clusterregistrierungsansatz angeben können:

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

Hinweis

Wenn registryPath im zugrunde liegenden Helm-Paket leer bleibt, tritt bei der SNS-Bereitstellung während des Imagedownloads ein Fehler auf.

Weitere Informationen zur Verwendung einer Clusterregistrierung finden Sie in der Konzeptdokumentation.

Empfehlungen für Unveränderlichkeitseinschränkungen

Einschränkungen für die Unveränderlichkeit verhindern Änderungen an einer Datei oder einem Verzeichnis. Beispielsweise kann eine unveränderliche Datei nicht geändert oder umbenannt werden. Vermeiden Sie die Verwendung von änderbaren Tags wie latest, , devoder stable. Wenn deployment.yaml für latest in .Values.image.tag verwendet wird, tritt bei der Bereitstellung ein Fehler auf.

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

Empfehlungen für CRD-Deklaration und Verbrauchsaufteilung

Es wird empfohlen, die Deklaration und Verwendung von Kundenressourcendefinitionen (CRDs) in separate Helm-Diagramme aufzuteilen, um Updates zu unterstützen. Ausführliche Informationen finden Sie in der Helm-Dokumentation zum Trennen von Diagrammen.

Empfehlungen für die Imageversionstagging

Um konsistente und vorhersagbare Bereitstellungen sicherzustellen, empfehlen wir Folgendes für alle Containerimages:

  • Vermeiden Sie die Verwendung :latest in Produktionsumgebungen.
    • Die Verwendung von „latest“ kann zu unerwartetem Verhalten führen, da sich das tatsächliche Bild hinter „latest“ ohne vorherige Ankündigung ändern kann.
    • Wenn sich der Tagwert in einer Clusterregistrierung ändert, der Tagname jedoch unverändert bleibt, lädt die Clusterregistrierung das aktualisierte Image nicht erneut herunter.
    • Dies kann dazu führen, dass veraltete oder inkonsistente Images ausgeführt werden.
  • Verwenden Sie stattdessen immer unveränderliche Tags wie :1.4.2
  • Stellen Sie sicher, dass jeder Build ein eindeutiges Tag erzeugt, und überschreiben Sie keine vorhandenen Tags.

Diese Methoden tragen dazu bei, Bereitstellungsprobleme zu vermeiden und die Rückverfolgbarkeit, Rollbacksicherheit und Sicherheitscompliance zu verbessern.

Empfehlungen für die sequenzielle Sortierung von nfApplication

Standardmäßig werden CNF-Anwendungen basierend auf der Reihenfolge installiert oder aktualisiert, in der sie in der NFDV angezeigt werden. Für den Löschvorgang werden die CNF-Anwendungen in der angegebenen umgekehrten Reihenfolge gelöscht. Wenn Sie eine bestimmte Reihenfolge von CNF-Anwendungen definieren müssen, die sich von der Standardreihenfolge unterscheidet, verwenden Sie dependsOnProfile, um eine eindeutige Sequenz für Installations-, Update- und Löschvorgänge zu definieren.

Verwenden von dependsOnProfile

Sie können dependsOnProfile in der NFDV verwenden, um die Reihenfolge der Helm-Ausführungen für CNF-Anwendungen zu steuern. Im folgenden Beispiel:

  • Während eines Installationsvorgangs werden die CNF-Anwendungen in der folgenden Reihenfolge bereitgestellt: dummyApplication1, dummyApplication2, dummyApplication.
  • Während eines Aktualisierungsvorgangs werden die CNF-Anwendungen in der folgenden Reihenfolge aktualisiert: dummyApplication2, dummyApplication1, dummyApplication.
  • Während eines Löschvorgangs werden die CNF-Anwendungen in der folgenden Reihenfolge gelöscht: 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"
    }
}

Häufige Fehler mit "dependsOnProfile"

Wenn der in der NFDV bereitgestellte dependsOnProfile-Code ungültig ist, schlägt der NF-Vorgang mit einem Validierungsfehler fehl. Die Meldung für den Validierungsfehler wird in der Vorgangsstatusressource angezeigt und ähnelt folgendem Beispiel:

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