Najlepsze rozwiązania dotyczące pakietu Helm

Helm to menedżer pakietów dla platformy Kubernetes, który ułatwia zarządzanie cyklem życia aplikacji. Pakiety Helm nazywają się chartami i składają się z plików konfiguracyjnych YAML oraz plików szablonów. Po wykonaniu operacji Helm charty są przekształcane w pliki manifestów Kubernetes, aby uruchomić odpowiednie działania związane z cyklem życia aplikacji. Aby uzyskać najbardziej wydajną integrację z programem Azure Operator Service Manager, postępuj zgodnie z tymi zalecanymi najlepszymi rozwiązaniami podczas tworzenia wykresów programu Helm.

Zagadnienia dotyczące „registryPath” i „imagePullSecrets”

Każdy chart Helm zazwyczaj wymaga parametrów registryPath i imagePullSecrets. Najczęściej te parametry są uwidaczniane w values.yaml pliku. Na początku menedżer usług operatora platformy Azure zależy od wydawców zarządzających tymi wartościami w ścisły sposób (starsze podejście), które mają zostać zastąpione odpowiednimi wartościami platformy Azure podczas wdrażania. Ale nie wszyscy wydawcy mogą łatwo przestrzegać ścisłego zarządzania tymi wartościami. Niektóre wykresy ukrywają registryPath i/lub imagePullSecrets za warunkowymi lub innymi ograniczeniami wartości, które nie zawsze były spełnione. Niektóre wykresy deklarują registryPath i/lub imagePullSecrets jako tablicę, a nie jako oczekiwany nazwany ciąg.

Aby zmniejszyć wymagania dotyczące zgodności wydawców, program Azure Operator Service Manager wprowadził dwie ulepszone metody: injectArtifactStoreDetail i rejestr klastrów. Te nowsze metody nie zależą od pojawienia się registryPath ani imagePullSecrets w pakiecie Helm. Zamiast tego te metody używają mechanizmu webhook do bezpośredniego wstrzykiwania odpowiednich wartości platformy Azure do operacji podu.

Podsumowanie metody registryPath i imagePullSecrets

Wszystkie trzy metody są obecnie obsługiwane zgodnie z opisem w tym artykule. Wybierz najlepszą opcję dla funkcji sieciowej (NF) i przypadku użycia.

Spuścizna:

  • Wymaga sparametryzowania registryPath i imagePullSecrets w wartościach Helm oraz szablonach wdrożenia w celu podmiany.
  • Hostuje obrazy w usłudze Azure Container Registry.

InjectArtifactStoreDetail:

  • Używa mechanizmu webhook do wstrzykiwania registryPath i imagePullSecrets bezpośrednio do operacji poda, przy minimalnej zależności od Helma.
  • Hostuje obrazy w usłudze Azure Container Registry.

Rejestr klastrów:

  • Używa mechanizmu webhook do bezpośredniego wstrzykiwania registryPath i imagePullSecrets do operacji na podach, bez zależności od Helma.
  • Przechowuje obrazy w rozszerzeniu lokalnego operatora funkcji sieciowej (NFO).

We wszystkich trzech przypadkach usługa Azure Operator Service Manager zastępuje dowolne wartości udostępniane w szablonach wartościami Azure. Jedyną różnicą jest metoda podstawienia.

Starsze wymagania dotyczące registryPath i imagePullSecrets

Menedżer usług operatora platformy Azure używa usługi Menedżer funkcji sieci platformy Azure do wdrażania konteneryzowanych funkcji sieciowych (CNFs). W starszej metodzie usługa Azure Network Function Manager podstawia wartości registryPath i imagePullSecrets kontenera usługi Azure Operator Service Manager w operacji Helm podczas wdrażania funkcji sieciowych.

Przykład przestarzałej metody

Poniższy szablon wdrażania programu Helm przedstawia przykład sposobu uwidacznienia registryPath i 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

Poniższy szablon values.yaml pokazuje przykład, jak można podać wartości registryPath i imagePullSecrets:

global: 
   imagePullSecrets: [] 
   registryPath: ""

Poniższy plik values.schema.json pokazuje przykład definiowania wartości registryPath i 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" ], 
      } 
   } 
}

Poniższa treść żądania definicji funkcji sieciowej w wersji (NFDV) pokazuje przykład, jak można podać wartości registryPath i imagePullSecrets przy wdrażaniu:

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

W poprzednich przykładach:

  • Wartość registryPath jest ustawiana bez żadnego prefiksu, takiego jak https:// lub oci://. W razie potrzeby zdefiniuj prefiks w pakiecie Helm.
  • imagePullSecrets i registryPath należy podać podczas wdrażania NFDV.

Inne uwagi

Podczas korzystania ze starszej metody należy wziąć pod uwagę następujące zalecenia.

Unikanie odwołań do rejestru zewnętrznego

Odwołania do rejestru zewnętrznego mogą powodować problemy z walidacją. Jeśli na przykład deployment.yaml używa zakodowanej ścieżki rejestru lub odwołań do rejestru zewnętrznego, weryfikacja zakończy się niepowodzeniem.

Wykonywanie ręcznych walidacji

Przejrzyj obrazy i specyfikacje kontenerów, aby upewnić się, że obrazy mają prefiks registryPath oraz że pole imagePullSecrets jest wypełnione wartością secretName:

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

Oto kolejny przykład:

 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>

Używanie repozytorium obrazów statycznych i tagów

Każdy chart Helm powinien zawierać statyczne repozytorium obrazów i tagi. Wartości statyczne można ustawić za pomocą jednej z następujących metod:

  • W image wierszu
  • W values.yaml, bez ujawniania tych wartości w NFDV

NFDV powinien odpowiadać statycznemu zestawowi chartów Helm i obrazów. Aktualizujesz wykresy i grafiki wyłącznie przez opublikowanie nowego NFDV, jak pokazano w poniższych przykładach:

 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 requirements for registryPath and imagePullSecrets (wymagania dotyczące metody injectArtifactStoreDetails dla metody registryPath i imagePullSecrets)

W niektórych przypadkach wykresy programu Helm innych firm mogą nie być w pełni zgodne z wymaganiami programu Azure Operator Service Manager dla programu registryPath. W takich przypadkach można użyć injectArtifactStoreDetails, aby uniknąć wprowadzania zmian związanych ze zgodnością w pakietach Helm.

Po włączeniu injectArtifactStoreDetails można użyć metody webhooka, aby dynamicznie wstrzykiwać odpowiednie registryPath i imagePullSecrets podczas operacji poda. Ta metoda zastępuje wartości skonfigurowane w pakiecie Helm. Nadal musisz używać prawidłowych fikcyjnych wartości tam, gdzie występują odwołania do registryPath i imagePullSecrets, zwykle w sekcji global w values.yaml.

W poniższym values.yaml przykładzie pokazano, jak można podać wartości registryPath i imagePullSecrets na potrzeby zgodności z podejściem injectArtifactStoreDetails:

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

Uwaga

Jeśli registryPath w bazowym pakiecie Helm pozostanie puste, wdrożenie usługi Site Network Service (SNS) nie powiedzie się podczas pobierania obrazu.

Za pomocą metody injectArtifactStoreDetails

Aby włączyć injectArtifactStoreDetails, ustaw parametr installOptions w sekcji roleOverrides zasobu NF na true, jak pokazano w poniższym przykładzie:

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

Uwaga

Pakiet chartu Helm musi nadal udostępniać poprawnie sformatowane wartości registryPath i imagePullSecrets.

Wymagania dotyczące rejestru klastra dla elementu registryPath i imagePullSecrets

W rejestrze klastrów obrazy są kopiowane z usługi Azure Container Registry do lokalnego repozytorium platformy Docker w klastrze Nexus Kubernetes. Używasz metody webhooka do dynamicznego wstrzykiwania odpowiednich wartości registryPath i imagePullSecrets podczas operacji na podzie. Ta metoda zastępuje wartości skonfigurowane w pakiecie Helm. Nadal musisz używać prawidłowych fikcyjnych wartości tam, gdzie występują odwołania do registryPath i imagePullSecrets, zwykle w sekcji global w values.yaml.

W poniższym przykładzie values.yaml pokazano, jak można podać wartości registryPath i imagePullSecrets na potrzeby zgodności z podejściem rejestru klastra:

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

Uwaga

Jeśli registryPath pozostanie puste w bazowym pakiecie Helm, wdrożenie SNS nie powiedzie się podczas pobierania obrazu.

Aby uzyskać więcej informacji na temat korzystania z rejestru klastrów, zobacz dokumentację koncepcji.

Zalecenia dotyczące ograniczeń niezmienności

Ograniczenia niezmienności uniemożliwiają zmianę pliku lub katalogu. Na przykład, pliku niezmienialnego nie można zmienić ani zmienić jego nazwy. Należy unikać używania tagów modyfikowalnych, takich jak latest, devlub stable. Jeśli na przykład deployment.yaml używa latest do .Values.image.tag, wdrożenie nie powiedzie się.

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

Zalecenia dotyczące rozdzielenia deklaracji CRD i ich użycia

Zalecamy podzielenie deklaracji i użycia definicji zasobów klienta (CRD) na oddzielne wykresy programu Helm w celu obsługi aktualizacji. Aby uzyskać szczegółowe informacje, zobacz dokumentację programu Helm dotyczącą oddzielania wykresów.

Zalecenia dotyczące tagowania wersji obrazu

Aby zapewnić spójne i przewidywalne wdrożenia, zalecamy następujące elementy dla wszystkich obrazów kontenerów:

  • Unikaj używania :latest w środowiskach produkcyjnych.
    • Użycie tagu latest może powodować nieoczekiwane zachowanie, ponieważ obraz przypisany do tagu latest może zmienić się bez uprzedzenia.
    • W konfiguracji rejestru klastra, jeśli wartość tagu zmieni się, ale nazwa tagu pozostanie taka sama, rejestr klastra nie pobierze ponownie zaktualizowanego obrazu.
    • Może to prowadzić do uruchamiania nieaktualnych lub niespójnych obrazów.
  • Zamiast tego zawsze używaj niezmiennych tagów, takich jak :1.4.2
  • Upewnij się, że każda kompilacja tworzy unikatowy tag, nie zastępuje istniejących tagów.

Te praktyki pomagają zapobiegać problemom z wdrażaniem oraz zwiększają identyfikowalność, bezpieczeństwo wycofywania zmian i zgodność z wymogami bezpieczeństwa.

Zalecenia dotyczące sekwencyjnego porządkowania aplikacji nfApplication

Domyślnie aplikacje CNF są instalowane lub aktualizowane na podstawie kolejności, w jakiej są wyświetlane w systemie plików NFDV. W przypadku operacji usuwania aplikacje CNF są usuwane w określonej kolejności odwrotnej. Jeśli musisz zdefiniować określoną kolejność aplikacji CNF, która różni się od domyślnej, użyj polecenia dependsOnProfile , aby zdefiniować unikatową sekwencję dla operacji instalacji, aktualizacji i usuwania.

Jak używać metody dependsOnProfile

Za pomocą dependsOnProfile systemu plików NFDV można kontrolować sekwencję wykonań programu Helm dla aplikacji CNF. W poniższym przykładzie:

  • Podczas operacji instalacji aplikacje CNF są wdrażane w następującej kolejności: dummyApplication1, , dummyApplication2dummyApplication.
  • Podczas operacji aktualizacji aplikacje CNF są aktualizowane w następującej kolejności: dummyApplication2, , dummyApplication1dummyApplication.
  • Podczas operacji usuwania aplikacje CNF są usuwane w następującej kolejności: dummyApplication2, , dummyApplication1dummyApplication.
{
    "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"
    }
}

Typowe błędy dotyczące pliku dependsOnProfile

Obecnie, jeśli dependsOnProfile kod podany w NFDV jest nieprawidłowy, operacja NF kończy się niepowodzeniem z powodu błędu walidacji. Komunikat o błędzie weryfikacji jest wyświetlany w zasobie stanu operacji i wygląda podobnie do następującego przykładu:

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

Najlepsze rozwiązania dotyczące wdrażania programu Helm 4

Program Helm jest standardowym menedżerem pakietów dla platformy Kubernetes od czasu jej początkowej wersji w 2016 roku. Jego ewolucja ściśle odzwierciedlała rozwój samego Kubernetes:

  • Helm v2 (2016–2019): Wprowadził pakietowanie aplikacji oparte na chartach, ale opierał się na komponencie działającym po stronie serwera (Tiller), co budziło obawy dotyczące bezpieczeństwa i wielodzierżawności.
  • Helm w wersji 3 (2019–2025): Usunięto Tiller, przenosząc się do modelu tylko dla klienta z ulepszonym zabezpieczeniami i użytecznością. Ta wersja stała się standardem branżowym i z czasem zyskała kolejne usprawnienia, zachowując przy tym wsteczną kompatybilność.

Po prawie sześciu latach rozwoju Helma v3 projekt zgromadził dług techniczny, ograniczenia architektoniczne i problemy związane z bezpieczeństwem, których nie mógł rozwiązać bez wprowadzania niekompatybilnych zmian. Ta sytuacja doprowadziła do wydania programu Helm w wersji 4 pod koniec 2025 roku.

Co oznacza Helm 4

Helm 4 to znacząca ewolucja architektury, a nie przyrostowe uaktualnienie. Jej głównymi celami są:

  • Dopasowanie do nowoczesnych wzorców wdrażania platformy Kubernetes
  • Usuwanie starszych zachowań programu Helm w wersji 3
  • Zwiększanie rozszerzalności, łatwość konserwacji i bezpieczeństwo

Kluczowe zmiany wprowadzone w programie Helm 4 obejmują:

  • Server-Side Apply (SSA): zastępuje starsze trzykierunkowe podejście scalania i dostosowuje wdrożenia do semantyki uzgodnień natywnych dla platformy Kubernetes.
  • Przeprojektowany system wtyczek: wprowadza bardziej rozszerzalną architekturę, w tym opcjonalne wtyczki oparte na zestawie WebAssembly, co zapewnia lepszą izolację i elastyczność.
  • Ulepszone śledzenie zasobów: wykorzystuje nowsze mechanizmy stanu platformy Kubernetes, takie jak kstatus, w celu zapewnienia dokładniejszego raportowania stanu wdrożenia.
  • Modernizacja wewnętrzna: usuwa dług techniczny i stanowi podstawę przyszłych innowacji i poprawy wydajności.

Co ważne, program Helm 4 utrzymuje zgodność z istniejącymi wykresami helm w wersji 3, umożliwiając organizacjom stopniowe wdrażanie programu Helm 4 bez konieczności wprowadzania natychmiastowych zmian w wykresach lub artefaktach wdrażania.

Znaczenie dla wydawców AOSM

Zespół AOSM planuje obsługę programu Helm 4 za pośrednictwem dwóch kluczowych kamieni milowych:

  • Najpierw zespół AOSM wyda wersję NFO, która obejmuje program Helm 4.1.4 działający w trybie "zgodności". Ten tryb zachowuje zachowanie programu Helm 3.18, dzięki czemu wydawcy mogą wdrażać program Helm 4 bez modyfikowania istniejących wykresów lub artefaktów.
    • Możesz już dziś przetestować tę wersję zapoznawczą NFO w laboratorium UKSouth.
  • Po drugie, zespół AOSM wydaje wersję NFO, która usuwa dostosowania zapewniające zgodność i umożliwia pełne działanie Helm 4. Wydawcy mogą przyjąć tę wersję, gdy będą na to gotowi, mając świadomość, że mogą być konieczne zmiany w wykresach i artefaktach.
    • Zespół AOSM planuje tę wersję NFO do testów wydawców w IV kwartale roku kalendarzowego 2026.

Wydawcy nadal mogą elastycznie wybierać sposób działania Helm podczas instalacji NFO. NFO domyślnie działa w „trybie zgodności”, oferując jednocześnie podczas instalacji opcję włączenia pełnego działania Helm 4. Ta funkcja jest ograniczona do zakresu klastra, co oznacza, że wszystkie wdrożenia w klastrze muszą używać tego samego trybu operacyjnego Programu Helm.

Szczegóły trybu zgodności

Następujące ustawienia zachowują zachowanie programu Helm 3 podczas uruchamiania programu Helm 4 w trybie zgodności:

  • Bardziej rygorystyczna weryfikacja schematu
    • Helm 4 wprowadza bardziej rygorystyczną walidację, która odrzuca slice’y typu Go, takie jak []map[string]interface{}, podczas walidacji tablic JSON. To zachowanie może powodować błędy, gdy NFO wprowadza wartości imagePullSecrets.
    • NFO aktualizuje logikę wstrzykiwania wartości, aby używać zamiast tego []interface{}, oraz poddaje przeglądowi podobne ścieżki kodu, aby zapewnić zgodność.
  • Server-Side Apply (SSA) domyślnie włączone
    • Program Helm 4 weryfikuje renderowane manifesty względem schematu openAPI klastra przed zastosowaniem zasobów. Charty zawierające nieprawidłowe definicje pól, które wcześniej były tolerowane przez Helm 3, mogą nie przejść walidacji.
    • Tryb zgodności wyłącza SSA podczas instalacji i aktualizacji, aby zachować sposób działania Helm 3.
  • Nowy model oczekiwania
    • Helm 4 domyślnie używa modelu oczekiwania opartego na zdarzeniach, który wymaga uprawnień watch w Kubernetes. To zachowanie może zakończyć się niepowodzeniem w klastrach Nexus, jeśli wymagane uprawnienia RBAC nie są dostępne.
    • Tryb zgodności ustawia sposób oczekiwania na LegacyStrategy, zachowując semantykę odpytywania Helm 3.
  • Utwórz ponownie usunięty element
    • Program Helm 4 usuwa obsługę elementu Upgrade.Recreate. Chociaż oczekuje się, że wpływ na środowisko uruchomieniowe będzie niski, wartości skonfigurowane przez klienta w crD nie będą już miały żadnego wpływu.
    • Tryb zgodności zachowuje pole CRD w celu zachowania zgodności wstecznej, ale ignoruje je podczas wykonywania operacji Helm 4.
  • Weryfikacja metaschemy schematu
    • Program Helm 4 weryfikuje values.schema.json względem metaschemy schematu JSON. Wykresy zawierające niezgodne definicje schematu są odrzucane przed rozpoczęciem walidacji wartości. Wiadomo, że takie zachowanie wpływa na niektóre wykresy wydawców.
    • Tryb zgodności powoduje ustawienie SkipSchemaValidation=true podczas operacji instalacji i uaktualniania.
  • Last updated on