From 20ed1a1ebd112de4ac3f099bea974c65ac141e37 Mon Sep 17 00:00:00 2001 From: Jonathan Tong Date: Fri, 21 Oct 2022 12:01:49 -0600 Subject: [PATCH] Update optional fields in controller contracts --- .../src/developer/architecture/controllers/cluster.md | 5 +++++ .../src/developer/architecture/controllers/machine.md | 11 +++++++++++ .../src/developer/providers/cluster-infrastructure.md | 2 +- .../src/developer/providers/machine-infrastructure.md | 6 +++--- 4 files changed, 20 insertions(+), 4 deletions(-) diff --git a/docs/book/src/developer/architecture/controllers/cluster.md b/docs/book/src/developer/architecture/controllers/cluster.md index 4cf263a41087..22f9394477f9 100644 --- a/docs/book/src/developer/architecture/controllers/cluster.md +++ b/docs/book/src/developer/architecture/controllers/cluster.md @@ -44,6 +44,11 @@ The `status` object **may** define several fields that do not affect functionali * `failureReason` - is a string that explains why a fatal error has occurred, if possible. * `failureMessage` - is a string that holds the message contained by the error. +* `failureDomains` - is a `FailureDomains` type indicating the failure domains that machines should be placed in. `FailureDomains` +is a map, defined as `map[string]FailureDomainSpec`. A unique key must be used for each `FailureDomainSpec`. +`FailureDomainSpec` is defined as: + - `controlPlane` (bool): indicates if failure domain is appropriate for running control plane instances. + - `attributes` (`map[string]string`): arbitrary attributes for users to apply to a failure domain. Example: ```yaml diff --git a/docs/book/src/developer/architecture/controllers/machine.md b/docs/book/src/developer/architecture/controllers/machine.md index f4d974a197da..60a235f163c4 100644 --- a/docs/book/src/developer/architecture/controllers/machine.md +++ b/docs/book/src/developer/architecture/controllers/machine.md @@ -81,6 +81,12 @@ The `spec` object **must** at least one field defined: * `providerID` - a cloud provider ID identifying the machine. +#### Optional `spec` fields + +The `spec` object **may** define several fields that do not affect functionality if missing: + +* `failureDomain` - is a string identifying the failure domain the instance is running in. + #### Required `status` fields The `status` object **must** at least one field defined: @@ -93,6 +99,11 @@ The `status` object **may** define several fields that do not affect functionali * `failureReason` - is a string that explains why a fatal error has occurred, if possible. * `failureMessage` - is a string that holds the message contained by the error. +* `addresses` - is a `MachineAddresses` (a list of `MachineAddress`) which represents host names, external IP addresses, internal IP addresses, +external DNS names, and/or internal DNS names for the provider's machine instance. `MachineAddress` is +defined as: + - `type` (string): one of `Hostname`, `ExternalIP`, `InternalIP`, `ExternalDNS`, `InternalDNS` + - `address` (string) Example: ```yaml diff --git a/docs/book/src/developer/providers/cluster-infrastructure.md b/docs/book/src/developer/providers/cluster-infrastructure.md index a99d4c79c697..907ca246fd59 100644 --- a/docs/book/src/developer/providers/cluster-infrastructure.md +++ b/docs/book/src/developer/providers/cluster-infrastructure.md @@ -30,7 +30,7 @@ A cluster infrastructure provider must define an API type for "infrastructure cl meant to be suitable for programmatic interpretation 2. `failureMessage` (string): indicates there is a fatal problem reconciling the provider's infrastructure; meant to be a more descriptive value than `failureReason` - 3. `failureDomains` (`failureDomains`): the failure domains that machines should be placed in. `failureDomains` + 3. `failureDomains` (`FailureDomains`): the failure domains that machines should be placed in. `FailureDomains` is a map, defined as `map[string]FailureDomainSpec`. A unique key must be used for each `FailureDomainSpec`. `FailureDomainSpec` is defined as: - `controlPlane` (bool): indicates if failure domain is appropriate for running control plane instances. diff --git a/docs/book/src/developer/providers/machine-infrastructure.md b/docs/book/src/developer/providers/machine-infrastructure.md index 4a20e9fd87ba..db4cae023a14 100644 --- a/docs/book/src/developer/providers/machine-infrastructure.md +++ b/docs/book/src/developer/providers/machine-infrastructure.md @@ -37,11 +37,11 @@ A machine infrastructure provider must define an API type for "infrastructure ma meant to be suitable for programmatic interpretation 2. `failureMessage` (string): indicates there is a fatal problem reconciling the provider's infrastructure; meant to be a more descriptive value than `failureReason` - 3. `addresses` (`MachineAddress`): a list of the host names, external IP addresses, internal IP addresses, + 3. `addresses` (`MachineAddresses`): a list of the host names, external IP addresses, internal IP addresses, external DNS names, and/or internal DNS names for the provider's machine instance. `MachineAddress` is defined as: - - `type` (string): one of `Hostname`, `ExternalIP`, `InternalIP`, `ExternalDNS`, `InternalDNS` - - `address` (string) + - `type` (string): one of `Hostname`, `ExternalIP`, `InternalIP`, `ExternalDNS`, `InternalDNS` + - `address` (string) 7. Should have a conditions field with the following: 1. A Ready condition to represent the overall operational state of the component. It can be based on the summary of more detailed conditions existing on the same object, e.g. instanceReady, SecurityGroupsReady conditions.