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

このページでは、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. クラスタレベルまたは Namespace レベルの 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. 既存の 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 を使用するケース

ほとんどの場合、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 レスポンスになることが想定されます。

Config Connector によって Kubernetes リソース仕様に入力される未指定のフィールドは、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
  • EventarcTrigger
  • 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
  • RecaptchaEnterpriseKey
  • RedisInstance
  • ResourceManagerLien
  • ResourceManagerPolicy
  • RunJob
  • RunService
  • SQLDatabase
  • SQLSSLCert
  • SQLUser
  • SecretManagerSecret
  • SecretManagerSecretVersion
  • サービス
  • ServiceDirectoryEndpoint
  • ServiceDirectoryNamespace
  • ServiceDirectoryService
  • ServiceIdentity
  • ServiceNetworkingConnection
  • SourceRepoRepository
  • SpannerDatabase
  • SpannerInstance
  • StorageBucket
  • StorageBucketAccessControl
  • StorageDefaultObjectAccessControl
  • StorageNotification
  • StorageTransferJob
  • VPCAccessConnector

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

種類名 バージョン
LoggingLogMetric 1.118.1