未指定のフィールドを無視する

このページでは、spec フィールドのデフォルトの入力動作と、デフォルトの動作を Merge から推奨される動作 Absent に変更する方法について説明します。バージョン 1.114.0 以降で追加された CRD を使用している場合、それらの CRD は Absent の動作のみを使用するため、このページは適用されない可能性があります。Merge をサポートする CRD の一覧については、このページの Merge をサポートする CRD セクションをご覧ください。

spec 個のフィールドの入力動作

Config Connector がリソースを作成するときに、Kubernetes リソース仕様で指定されていないフィールドには、Absent と Merge の 2 つの異なるデフォルトの入力動作が見られます。

欠落

Absent は推奨の動作です。Config Connector は、未指定のフィールドを仕様に入力しません。

バージョン 1.114.0 以降で追加された CRD の場合、デフォルトの入力動作は Absent です。これは、これらの CRD がサポートする唯一の入力動作でもあります。これらのリソース CR では、cnrm.cloud.google.com/state-into-spec アノテーションの値は absent です。

統合

Merge は、1.114.0 以降で追加された CRD ではサポートされていない動作です。spec フィールドは、読み取り可能でない場合を除き、調整が正常に完了すると API から値を取得します。詳しくは、フィールドを外部で管理するをご覧ください。

Config Connector バージョン 1.113.0 以前でサポートされている CRD の場合、デフォルトの入力動作は Merge です。Merge をサポートする CRD の一覧については、このページの Merge をサポートする CRD セクションをご覧ください。これらのリソース CR の cnrm.cloud.google.com/state-into-spec アノテーションのデフォルト値は merge です。未指定のフィールドの仕様への入力をスキップするの手順に沿って、入力動作を Absent に構成することもできます。

デフォルトでは、これらのリソース CR で、元の YAML で指定されていないフィールドは常に CR 仕様に表示されます。つまり、kubectl get <resource kind> <resource name> -oyaml を実行すると、仕様の多くのフィールドが適用された YAML にありません。

たとえば、CRD スキーマで foo と bar という名前の 2 つのフィールドを仕様に指定できて、適用された YAML ファイルに foo のみが指定されているとします。

spec:
  foo: "foo"

YAML が正常に適用され、リソースが UpToDate の場合、bar という名前の別のフィールドが CR に表示されます。

spec:
  foo: "foo"
  bar: "bar"

Config Connector とGoogle Cloud APIs 間のやり取りは複雑であるため、デフォルトの動作を変更して、Kubernetes リソース仕様に未指定のフィールドを入力しないようにすることをおすすめします。

未指定のフィールドの仕様への入力をスキップする

Config Connector バージョン 1.113.0 以前でサポートされている CRD の場合、次のいずれかの方法で、未指定のフィールドの仕様への入力をスキップできます。

  • クラスタレベルまたは Namespace レベルの stateIntoSpec オーバーライドを Absent に構成します。
  • リソースの cnrm.cloud.google.com/state-into-spec アノテーションの値を absent として指定します。

クラスタレベルまたは Namespace レベルの stateIntoSpec オーバーライドを構成する

Config Connector のインストール時または Config Connector のインストールを更新するときに、ConfigConnector CR または ConfigConnectorContext CR でクラスタレベルまたは Namespace レベルの stateIntoSpec オーバーライドを Absent に構成できます。

spec:
  stateIntoSpec: Absent

これにより、新しいリソース YAML で cnrm.cloud.google.com/state-into-spec アノテーションを指定しないと、クラスタまたは名前空間で作成された新しいリソースの spec フィールドの入力動作にデフォルトの Absent が設定されます。つまり、Config Connector は、これらのリソースの Kubernetes リソース仕様への未指定のフィールドの入力をスキップします。

stateIntoSpec フィールドにデフォルト値はありません。Config Connector は、cnrm.cloud.google.com/state-into-spec アノテーションの値に基づいて spec フィールドの入力動作を決定し、以下のロジックに従ってアノテーションの値を決定します。

  1. cnrm.cloud.google.com/state-into-spec アノテーションの値が指定されていて有効な場合は、その値を直接使用します。
  2. アノテーションが指定されていない場合は、ConfigConnectorContext CR の stateIntoSpec フィールドの対応する値を使用します。
  3. ConfigConnectorContext CR が存在しないか、stateIntoSpec フィールドが指定されていない場合は、ConfigConnector CR の stateIntoSpec フィールドの対応する値を使用します。
  4. ConfigConnector CR が存在しないか、stateIntoSpec フィールドが指定されていない場合は、spec フィールドの入力動作で説明されている CRD に基づくデフォルトの動作を使用します。

バージョン 1.114.0 以降で追加された唯一の入力動作 CRD は、cnrm.cloud.google.com/state-into-spec アノテーションまたは ConfigConnector CR または ConfigConnectorContext CR の stateIntoSpec フィールドに関係なく、Absent に従います。

リソースをすでに作成しているが、spec フィールドの入力動作を Absent に変更する場合は、次の操作を行います。

  1. ConfigConnector CR または ConfigConnectorContext CR で、クラスタレベルまたは Namespace レベルの stateIntoSpec オーバーライドが Absent になっていることを確認します。

  2. リソースを放棄して取得します。取得に使用する YAML 構成に、cnrm.cloud.google.com/state-into-spec アノテーションが含まれていないことを確認します。

リソースレベルの cnrm.cloud.google.com/state-into-spec アノテーションを指定する

YAML ファイルを作成するときに、cnrm.cloud.google.com/state-into-spec アノテーションの値を absent と指定できます。これにより、未指定のフィールドの Kubernetes リソース仕様への入力をスキップします。

metadata:
  annotations:
    cnrm.cloud.google.com/state-into-spec: absent

指定しない場合、このアノテーションにはデフォルト値の merge が設定されます。つまり、Config Connector によってすべての未指定フィールドが仕様に設定されます。このアノテーションは不変です。つまり、既存の Config Connector リソースのアノテーション値を更新することはできません。

リソースをすでに作成しているが、別の入力動作のためにこのアノテーションの値を変更する場合は、次の手順を行う必要があります。

  1. 既存の Kubernetes リソースにアノテーション cnrm.cloud.google.com/deletion-policy: abandon を追加して編集し、次のステップで削除しても基盤となる Google Cloud リソースが削除されないようにします。

  2. Kubernetes クラスタからリソースを削除します。

  3. リソースの YAML にアノテーション cnrm.cloud.google.com/state-into-spec: absent を追加します。

  4. （省略可）YAML から cnrm.cloud.google.com/deletion-policy: abandon を削除します。

  5. 更新された YAML を適用します。

このアノテーションによって導入される違いをさらに説明するために、次のスキーマの仕様があるとします。

foo1: string
foo2: string
bars:
- bar:
    br1: string
    br2: string
barz:
  bz1: string
  bz2: string

また、YAML で次のように仕様を指定しているとします。

spec:
  foo1: "foo1"
  bars:
  - br1: "1_br1"
  - br1: "2_br1"
  barz:
    bz1: "bz1"

デフォルトでは、作成された Kubernetes リソースの入力仕様は次のようになります。

spec:
  foo1: "foo1"
  foo2: "foo2"
  bars:
  - br1: "1_br1"
    br2: "1_br2"
  - br1: "2_br1"
    br2: "2_br2"
  barz:
    bz1: "bz1"
    bz2: "bz2"

cnrm.cloud.google.com/state-into-spec: absent を設定すると、作成された Kubernetes リソースの最終的な仕様は次のようになります。

spec:
  foo1: "foo1"
  bars:
  - br1: "1_br1"
  - br1: "2_br1"
  barz:
    bz1: "bz1"

cnrm.cloud.google.com/state-into-spec: absent を使用するケース

ほとんどの場合、cnrm.cloud.google.com/state-into-spec: absent を設定して、spec フィールドの Absent の入力動作を取得します。Absent の入力動作が役立つ最も一般的なシナリオは次のとおりです。

リスト内の未指定のフィールドを外部で管理する

Config Connector は、Kubernetes リソース仕様のすべてのリスト フィールドをアトミック フィールドとして扱います。その結果、デフォルトでは、Config Connector の外部からリスト内のサブフィールドに対して行った変更は、Config Connector によって元に戻されます。ただし、このアノテーションを使用すると、Config Connector でリスト内のサブフィールドの管理を解除できます。詳細については、リソース仕様のリスト フィールドの動作をご覧ください。

構成管理ツールと Config Connector 間の競合を解決する

Config Sync や Argo CD などの構成管理ツールを使用している場合、構成管理ツールと Config Connector の間で競合が発生することがあります。たとえば、トラブルシューティング ガイドで説明されている KNV2005 エラーがあります。この種の問題の根本原因は次のとおりです。

  1. Config Connector は、仕様のリストに値が入力され、デフォルトでは指定されません。spec.bars[0].br2 は一例です。
  2. 構成管理ツールと Config Connector は、どちらもリスト フィールドをアトミックとして扱います。したがって、追加された spec.bars[0].br2 は、構成管理ツールでブレとして扱われ、drift を修正するために削除されます。

これらの問題を解決するには、Config Connector が未指定のフィールド spec.bars[0].br2 を仕様に追加しないように、cnrm.cloud.google.com/state-into-spec: absent を設定します。

GET / PUT の対称性の問題を解決する

GET / PUT の対称性は、REST API の設計原則を示します。具体的には、GET レスポンスが PUT リクエストとして同じ URL に送信されると、基になる REST リソースの状態に変更がない HTTP 200 OK レスポンスになることが想定されます。

Kubernetes リソース仕様で Config Connector によって入力される未指定のフィールドは、GET リクエストの結果です。つまり、今後の調整では、Config Connector が、GET リクエストから学習した未指定のフィールド値を使用して、PUT / PATCH リクエストを基盤となるGoogle Cloud API に送信するということです。通常、これは問題になりませんが、未指定のフィールド値が原因で、一部のGoogle Cloud APIs で PUT / PATCH リクエストが拒否される可能性があります。同じ例で、API 実装が GET / PUT の対称性の原則に違反している場合は、値「bz2」が設定された spec.barz.bz2 によって、HTTP 400 クライアント エラーやその他の予期しないレスポンスが発生する可能性があります。

このカテゴリの問題を回避するには、cnrm.cloud.google.com/state-into-spec: absent の設定を試して、調整中のエラーが消えるかどうかを確認します。

観測された状態

cnrm.cloud.google.com/state-into-spec: absent を設定する必要があるものの、未指定のフィールドから入力された値にソリューションが依存している場合は、これらのフィールドが CRD スキーマの status.observedState の下に存在することを確認してください。これらが status.observedState に表示されている場合、cnrm.cloud.google.com/state-into-spec: absent を設定すると、調整が正常に完了した後も未指定のフィールドの値にアクセスできます。

status.observedState フィールドには、最後に成功した調整で Config Connector がモニタリングした、リソースの選択されたモニタリング対象フィールドのライブ状態が含まれます。観測されたフィールドは、一般的なユースケースの依存関係であり、計算された spec フィールドである場合に選択されます。観測されたフィールドは CRD スキーマにあります。

必要な観測されたフィールドが見つからない場合は、公開バグトラッカーで既存の問題を確認するか、新しい問題を報告してください。

Merge をサポートする種類

Merge の入力動作をサポートする Config Connector の種類は次のとおりです。

  • AccessContextManagerAccessLevel
  • AccessContextManagerAccessPolicy
  • AccessContextManagerServicePerimeter
  • AlloyDBBackup
  • AlloyDBCluster
  • AlloyDBUser
  • ApigeeEnvironment
  • ApigeeOrganization
  • ArtifactRegistryRepository
  • BigQueryDataset
  • BigQueryJob
  • BigQueryTable
  • BigtableAppProfile
  • BigtableGCPolicy
  • BigtableInstance
  • BigtableTable
  • BillingBudgetsBudget
  • BinaryAuthorizationAttestor
  • BinaryAuthorizationPolicy
  • CertificateManagerCertificate
  • CertificateManagerCertificateMap
  • CertificateManagerCertificateMapEntry
  • CloudBuildTrigger
  • CloudFunctionsFunction
  • CloudIdentityGroup
  • CloudIdentityMembership
  • CloudSchedulerJob
  • ComputeAddress
  • ComputeBackendBucket
  • ComputeBackendService
  • ComputeDisk
  • ComputeExternalVPNGateway
  • ComputeFirewall
  • ComputeFirewallPolicy
  • ComputeFirewallPolicyAssociation
  • ComputeForwardingRule
  • ComputeHTTPHealthCheck
  • ComputeHTTPSHealthCheck
  • ComputeHealthCheck
  • ComputeImage
  • ComputeInstance
  • ComputeInstanceGroup
  • ComputeInstanceGroupManager
  • ComputeInstanceTemplate
  • ComputeInterconnectAttachment
  • ComputeNetwork
  • ComputeNetworkEndpointGroup
  • ComputeNetworkFirewallPolicy
  • ComputeNetworkPeering
  • ComputeNodeGroup
  • ComputeNodeTemplate
  • ComputePacketMirroring
  • ComputeProjectMetadata
  • ComputeRegionNetworkEndpointGroup
  • ComputeReservation
  • ComputeResourcePolicy
  • ComputeRoute
  • ComputeRouter
  • ComputeRouterInterface
  • ComputeRouterNAT
  • ComputeRouterPeer
  • ComputeSSLCertificate
  • ComputeSSLPolicy
  • ComputeSecurityPolicy
  • ComputeServiceAttachment
  • ComputeSharedVPCHostProject
  • ComputeSharedVPCServiceProject
  • ComputeSnapshot
  • ComputeSubnetwork
  • ComputeTargetGRPCProxy
  • ComputeTargetHTTPProxy
  • ComputeTargetHTTPSProxy
  • ComputeTargetInstance
  • ComputeTargetPool
  • ComputeTargetSSLProxy
  • ComputeTargetTCPProxy
  • ComputeTargetVPNGateway
  • ComputeURLMap
  • ComputeVPNGateway
  • ComputeVPNTunnel
  • ConfigControllerInstance
  • ContainerAnalysisNote
  • ContainerAttachedCluster
  • ContainerCluster
  • ContainerNodePool
  • DLPDeidentifyTemplate
  • DLPInspectTemplate
  • DLPJobTrigger
  • DLPStoredInfoType
  • DNSManagedZone
  • DNSPolicy
  • DNSRecordSet
  • DataFusionInstance
  • DataflowFlexTemplateJob
  • DataflowJob
  • DataprocAutoscalingPolicy
  • DataprocCluster
  • DataprocWorkflowTemplate
  • EdgeContainerCluster
  • EdgeContainerNodePool
  • EdgeContainerVpnConnection
  • EdgeNetworkNetwork
  • EdgeNetworkSubnet
  • Eventarc トリガー
  • FilestoreBackup
  • FilestoreInstance
  • FirestoreIndex
  • フォルダ
  • GKEHubFeature
  • GKEHubMembership
  • IAMAccessBoundaryPolicy
  • IAMAuditConfig
  • IAMCustomRole
  • IAMPartialPolicy
  • IAMPolicy
  • IAMPolicyMember
  • IAMServiceAccount
  • IAMServiceAccountKey
  • IAMWorkforcePool
  • IAMWorkforcePoolProvider
  • IAMWorkloadIdentityPool
  • IAMWorkloadIdentityPoolProvider
  • IAPBrand
  • IAPIdentityAwareProxyClient
  • IdentityPlatformConfig
  • IdentityPlatformOAuthIDPConfig
  • IdentityPlatformTenant
  • IdentityPlatformTenantOAuthIDPConfig
  • KMSCryptoKey
  • KMSKeyRing
  • LoggingLogBucket
  • LoggingLogExclusion
  • LoggingLogSink
  • LoggingLogView
  • MemcacheInstance
  • MonitoringAlertPolicy
  • MonitoringGroup
  • MonitoringMetricDescriptor
  • MonitoringMonitoredProject
  • MonitoringNotificationChannel
  • MonitoringService
  • MonitoringServiceLevelObjective
  • MonitoringUptimeCheckConfig
  • NetworkConnectivityHub
  • NetworkConnectivitySpoke
  • NetworkSecurityAuthorizationPolicy
  • NetworkSecurityClientTLSPolicy
  • NetworkSecurityServerTLSPolicy
  • NetworkServicesEndpointPolicy
  • NetworkServicesGRPCRoute
  • NetworkServicesGateway
  • NetworkServicesHTTPRoute
  • NetworkServicesMesh
  • NetworkServicesTCPRoute
  • NetworkServicesTLSRoute
  • OSConfigGuestPolicy
  • OSConfigOSPolicyAssignment
  • PrivateCACAPool
  • PrivateCACertificate
  • PrivateCACertificateAuthority
  • PrivateCACertificateTemplate
  • プロジェクト
  • PubSubLiteReservation
  • PubSubSchema
  • PubSubSubscription
  • PubSubTopic
  • reCAPTCHA EnterpriseKey
  • RedisInstance
  • ResourceManagerLien
  • ResourceManagerPolicy
  • RunJob
  • RunService
  • SQLDatabase
  • SQLSSLCert
  • SQLUser
  • SecretManagerSecret
  • SecretManagerSecretVersion
  • サービス
  • ServiceDirectoryEndpoint
  • ServiceDirectoryNamespace
  • ServiceDirectoryService
  • ServiceIdentity
  • ServiceNetworkingConnection
  • SourceRepoRepository
  • SpannerDatabase
  • SpannerInstance
  • StorageBucket
  • StorageBucketAccessControl
  • StorageDefaultObjectAccessControl
  • StorageNotification
  • StorageTransferJob
  • VPC アクセス コネクタ

次の種類は、対応するバージョン以降の Merge の入力動作をサポートしていません。

種類名 バージョン
LoggingLogMetric 1.118.1