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

このページでは、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 の仕様への未指定のフィールドの入力をスキップできます。

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

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

Config Connector をインストールする際、または Config Connector のインストールを更新する際、クラスタレベルまたは名前空間レベルの stateIntoSpec を ConfigConnector CR または ConfigConnectorContext CR で 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. クラスタレベルまたは名前空間レベルの stateIntoSpec が ConfigConnector CR または ConfigConnectorContext CR で 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. アノテーション cnrm.cloud.google.com/deletion-policy: abandon を編集して既存の Kubernetes リソースに追加し、次のステップで削除しても基盤となる 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 を使用するケース

ほとんどの場合、spec フィールドに Absent の入力動作を取得するために、cnrm.cloud.google.com/state-into-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
  • AlloyDBInstance
  • AlloyDBUser
  • ApigeeEnvironment
  • ApigeeOrganization
  • ArtifactRegistryRepository
  • BigQueryDataset
  • BigQueryJob
  • BigQueryTable
  • BigtableAppProfile
  • BigtableGCPolicy
  • BigtableInstance
  • BigtableTable
  • BillingBudgetsBudget
  • BinaryAuthorizationAttestor
  • BinaryAuthorizationPolicy
  • CertificateManagerCertificate
  • CertificateManagerCertificateMap
  • CertificateManagerCertificateMapEntry
  • CertificateManagerDNSAuthorization
  • CloudBuildTrigger
  • CloudFunctionsFunction
  • CloudIdentityGroup
  • CloudIdentityMembership
  • CloudSchedulerJob
  • ComputeAddress
  • ComputeBackendBucket
  • ComputeBackendService
  • ComputeDisk
  • ComputeExternalVPNGateway
  • ComputeFirewall
  • ComputeFirewallPolicy
  • ComputeFirewallPolicyAssociation
  • ComputeFirewallPolicyRule
  • 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
  • EventarcTrigger
  • FilestoreBackup
  • FilestoreInstance
  • FirestoreIndex
  • フォルダ
  • GKEHubFeature
  • GKEHubFeatureMembership
  • 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
  • MonitoringDashboard
  • 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
  • RecaptchaEnterpriseKey
  • RedisInstance
  • ResourceManagerLien
  • ResourceManagerPolicy
  • RunJob
  • RunService
  • SQLDatabase
  • SQLInstance
  • SQLSSLCert
  • SQLUser
  • SecretManagerSecret
  • SecretManagerSecretVersion
  • サービス
  • ServiceDirectoryEndpoint
  • ServiceDirectoryNamespace
  • ServiceDirectoryService
  • ServiceIdentity
  • ServiceNetworkingConnection
  • SourceRepoRepository
  • SpannerDatabase
  • SpannerInstance
  • StorageBucket
  • StorageBucketAccessControl
  • StorageDefaultObjectAccessControl
  • StorageNotification
  • StorageTransferJob
  • VPCAccessConnector

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

種類名 バージョン
LoggingLogMetric 1.118.1