Documentation
¶
Overview ¶
The operationutils package provides helpers that glue together Clusters Service and asynchronous operations initiated by RP frontend pods in response to client requests.
For background reading about Azure's asynchronous operation contract for Resource Providers, see the Resource Provider Contract.
The ARO-HCP RP uses type api.Operation to represent an asynchronous operation. These structs get converted to JSON format and stored in Cosmos DB as so-called "operation documents".
At the time of this writing the RP backend defers most of the actual work involved in an operation to Clusters Service. The controllers in this package merely update operation documents in Cosmos DB to reflect the status of the actual operation in Clusters Service.
Generally speaking, the lifecycle of an operation document is as follows:
A frontend pod creates the operation document in Cosmos DB before responding to the client requesting the operation.
On the backend, the new operation document is first noticed by a "dispatch controller" that is dedicated to the operation's particular request type and resource type, such as "create cluster" or "delete node pool". The dispatch controller makes the appropriate calls to dispatch the operation to Clusters Service.
Once the operation is dispatched to Clusters Service, an "operation controller" begins polling the Clusters Service resource associated with the operation for status changes, and updates the operation document in Cosmos DB accordingly.
Meanwhile, the frontend will have exposed a status endpoint for this operation for the client to poll. (The endpoint is returned to the client as a header in the initial response.) The response body format of this endpoint is defined by Azure, but the operation document in Cosmos DB has all the required details to build a compliant response.
Operation documents in Cosmos DB are transient by way of a time-to-live (TTL) value. Once this TTL period (currently 7 days) expires, the Cosmos DB service will automatically delete the operation document.
Index ¶
- Constants
- func CompareOperationState(lhs, rhs *OperationState) int
- func ConvertClusterStatus(ctx context.Context, clusterServiceClient ocm.ClusterServiceClientSpec, ...) (coreapi.ProvisioningState, *coreapi.CloudErrorBody, error)
- func ConvertExternalAuthStatus(operation *coreapi.Operation, ...) (coreapi.ProvisioningState, *coreapi.CloudErrorBody, error)
- func ConvertNodePoolStatus(operation *coreapi.Operation, nodePoolStatus *arohcpv1alpha1.NodePoolStatus) (coreapi.ProvisioningState, *coreapi.CloudErrorBody, error)
- func NeedToPatchOperation(oldOperation *coreapi.Operation, newOperationStatus coreapi.ProvisioningState, ...) bool
- func PatchOperation(ctx context.Context, clock utilsclock.PassiveClock, ...) error
- func PostAsyncNotification(ctx context.Context, notificationClient *http.Client, ...) error
- func SetDeleteOperationAsCompleted(ctx context.Context, clock utilsclock.PassiveClock, ...) error
- func UpdateOperationStatus(ctx context.Context, clock utilsclock.PassiveClock, ...) error
- type ExternalAuthStateValue
- type NodePoolStateValue
- type OperationState
- type PostAsyncNotificationFunc
Constants ¶
const (
InflightChecksFailedProvisionErrorCode = "OCM4001"
)
Variables ¶
This section is empty.
Functions ¶
func CompareOperationState ¶
func CompareOperationState(lhs, rhs *OperationState) int
func ConvertClusterStatus ¶
func ConvertClusterStatus(ctx context.Context, clusterServiceClient ocm.ClusterServiceClientSpec, operation *coreapi.Operation, clusterStatus *arohcpv1alpha1.ClusterStatus, clusterServiceID metadataapi.InternalID) (coreapi.ProvisioningState, *coreapi.CloudErrorBody, error)
ConvertClusterStatus attempts to translate a ClusterStatus object from Cluster Service into an ARM provisioning state and, if necessary, a structured OData error.
func ConvertExternalAuthStatus ¶
func ConvertExternalAuthStatus(operation *coreapi.Operation, externalAuthStatus *arohcpv1alpha1.ExternalAuthStatus) (coreapi.ProvisioningState, *coreapi.CloudErrorBody, error)
func ConvertNodePoolStatus ¶
func ConvertNodePoolStatus(operation *coreapi.Operation, nodePoolStatus *arohcpv1alpha1.NodePoolStatus) (coreapi.ProvisioningState, *coreapi.CloudErrorBody, error)
ConvertNodePoolStatus attempts to translate a NodePoolStatus object from Cluster Service into an ARM provisioning state and, if necessary, a structured OData error.
func NeedToPatchOperation ¶
func NeedToPatchOperation(oldOperation *coreapi.Operation, newOperationStatus coreapi.ProvisioningState, newOperationError *coreapi.CloudErrorBody) bool
func PatchOperation ¶
func PatchOperation(ctx context.Context, clock utilsclock.PassiveClock, resourcesDBClient corecosmosstorage.ResourcesDBClient, oldOperation *coreapi.Operation, newOperationStatus coreapi.ProvisioningState, newOperationError *coreapi.CloudErrorBody, postAsyncNotificationFn PostAsyncNotificationFunc) error
PatchOperation patches the status and error fields of an OperationDocument.
func PostAsyncNotification ¶
func SetDeleteOperationAsCompleted ¶
func SetDeleteOperationAsCompleted(ctx context.Context, clock utilsclock.PassiveClock, resourcesDBClient corecosmosstorage.ResourcesDBClient, operation *coreapi.Operation, postAsyncNotificationFn PostAsyncNotificationFunc) error
SetDeleteOperationAsCompleted updates Cosmos DB to reflect a completed resource deletion.
func UpdateOperationStatus ¶
func UpdateOperationStatus(ctx context.Context, clock utilsclock.PassiveClock, resourcesDBClient corecosmosstorage.ResourcesDBClient, existingOperation *coreapi.Operation, newOperationStatus coreapi.ProvisioningState, newOperationError *coreapi.CloudErrorBody, postAsyncNotificationFn PostAsyncNotificationFunc) error
UpdateOperationStatus updates Cosmos DB to reflect an updated resource status. If the operation has an associated resource, both documents are updated atomically using a transactional batch to prevent a window where the operation shows a terminal status but the resource still reflects the previous provisioning state.
The resource update is skipped (but the operation is still updated) when:
- the operation has no ExternalID (no associated resource)
- the resource document was deleted (404 not found)
- a different operation now owns the resource (ActiveOperationID mismatch)
- the resource is already at the target non-terminal provisioning state
In all of these cases the operation document is still persisted and ARM is notified, so the operation reaches its terminal state and does not get stuck.
Types ¶
type ExternalAuthStateValue ¶
type ExternalAuthStateValue string
Copied from uhc-clusters-service, because the OCM SDK does not define this for some reason.
const ( ExternalAuthStateReady ExternalAuthStateValue = "ready" ExternalAuthStateUninstalling ExternalAuthStateValue = "uninstalling" ExternalAuthStateError ExternalAuthStateValue = "error" )
type NodePoolStateValue ¶
type NodePoolStateValue string
Copied from uhc-clusters-service, because the OCM SDK does not define this for some reason.
const ( NodePoolStateValidating NodePoolStateValue = "validating" NodePoolStatePending NodePoolStateValue = "pending" NodePoolStateInstalling NodePoolStateValue = "installing" NodePoolStateReady NodePoolStateValue = "ready" NodePoolStateUpdating NodePoolStateValue = "updating" NodePoolStateValidatingUpdate NodePoolStateValue = "validating_update" NodePoolStatePendingUpdate NodePoolStateValue = "pending_update" NodePoolStateUninstalling NodePoolStateValue = "uninstalling" NodePoolStateRecoverableError NodePoolStateValue = "recoverable_error" NodePoolStateError NodePoolStateValue = "error" )
type OperationState ¶
type OperationState struct {
// Source is a name that identifies the source of the operation state.
Source string `json:"source"`
ProvisioningState coreapi.ProvisioningState `json:"provisioningState"`
Message string `json:"message"`
}
func NewOperationState ¶
func NewOperationState(provisioningState coreapi.ProvisioningState, message string) *OperationState
NewOperationState creates a new operation state with the given provisioning state and message, without a source.
func PickWorstOperationState ¶
func PickWorstOperationState(states []*OperationState) (*OperationState, error)
PickWorstOperationState expects states pre-sorted and returns the worst state with merged messages.
func (*OperationState) WithSource ¶
func (s *OperationState) WithSource(source string) *OperationState
WithSource sets the source of the operation state.
type PostAsyncNotificationFunc ¶
func PostAsyncNotificationFn ¶
func PostAsyncNotificationFn(notificationClient *http.Client) PostAsyncNotificationFunc
Source Files
Directories