### First-Class Providers These changes implement support for first-class providers. First-class providers are provider plugins that are exposed as resources via the Pulumi programming model so that they may be explicitly and multiply instantiated. Each instance of a provider resource may be configured differently, and configuration parameters may be source from the outputs of other resources. ### Provider Plugin Changes In order to accommodate the need to verify and diff provider configuration and configure providers without complete configuration information, these changes adjust the high-level provider plugin interface. Two new methods for validating a provider's configuration and diffing changes to the same have been added (`CheckConfig` and `DiffConfig`, respectively), and the type of the configuration bag accepted by `Configure` has been changed to a `PropertyMap`. These changes have not yet been reflected in the provider plugin gRPC interface. We will do this in a set of follow-up changes. Until then, these methods are implemented by adapters: - `CheckConfig` validates that all configuration parameters are string or unknown properties. This is necessary because existing plugins only accept string-typed configuration values. - `DiffConfig` either returns "never replace" if all configuration values are known or "must replace" if any configuration value is unknown. The justification for this behavior is given [here](https://github.com/pulumi/pulumi/pull/1695/files#diff-a6cd5c7f337665f5bb22e92ca5f07537R106) - `Configure` converts the config bag to a legacy config map and configures the provider plugin if all config values are known. If any config value is unknown, the underlying plugin is not configured and the provider may only perform `Check`, `Read`, and `Invoke`, all of which return empty results. We justify this behavior becuase it is only possible during a preview and provides the best experience we can manage with the existing gRPC interface. ### Resource Model Changes Providers are now exposed as resources that participate in a stack's dependency graph. Like other resources, they are explicitly created, may have multiple instances, and may have dependencies on other resources. Providers are referred to using provider references, which are a combination of the provider's URN and its ID. This design addresses the need during a preview to refer to providers that have not yet been physically created and therefore have no ID. All custom resources that are not themselves providers must specify a single provider via a provider reference. The named provider will be used to manage that resource's CRUD operations. If a resource's provider reference changes, the resource must be replaced. Though its URN is not present in the resource's dependency list, the provider should be treated as a dependency of the resource when topologically sorting the dependency graph. Finally, `Invoke` operations must now specify a provider to use for the invocation via a provider reference. ### Engine Changes First-class providers support requires a few changes to the engine: - The engine must have some way to map from provider references to provider plugins. It must be possible to add providers from a stack's checkpoint to this map and to register new/updated providers during the execution of a plan in response to CRUD operations on provider resources. - In order to support updating existing stacks using existing Pulumi programs that may not explicitly instantiate providers, the engine must be able to manage the "default" providers for each package referenced by a checkpoint or Pulumi program. The configuration for a "default" provider is taken from the stack's configuration data. The former need is addressed by adding a provider registry type that is responsible for managing all of the plugins required by a plan. In addition to loading plugins froma checkpoint and providing the ability to map from a provider reference to a provider plugin, this type serves as the provider plugin for providers themselves (i.e. it is the "provider provider"). The latter need is solved via two relatively self-contained changes to plan setup and the eval source. During plan setup, the old checkpoint is scanned for custom resources that do not have a provider reference in order to compute the set of packages that require a default provider. Once this set has been computed, the required default provider definitions are conjured and prepended to the checkpoint's resource list. Each resource that requires a default provider is then updated to refer to the default provider for its package. While an eval source is running, each custom resource registration, resource read, and invoke that does not name a provider is trapped before being returned by the source iterator. If no default provider for the appropriate package has been registered, the eval source synthesizes an appropriate registration, waits for it to complete, and records the registered provider's reference. This reference is injected into the original request, which is then processed as usual. If a default provider was already registered, the recorded reference is used and no new registration occurs. ### SDK Changes These changes only expose first-class providers from the Node.JS SDK. - A new abstract class, `ProviderResource`, can be subclassed and used to instantiate first-class providers. - A new field in `ResourceOptions`, `provider`, can be used to supply a particular provider instance to manage a `CustomResource`'s CRUD operations. - A new type, `InvokeOptions`, can be used to specify options that control the behavior of a call to `pulumi.runtime.invoke`. This type includes a `provider` field that is analogous to `ResourceOptions.provider`.
384 lines
17 KiB
TypeScript
384 lines
17 KiB
TypeScript
// Copyright 2016-2018, Pulumi Corporation.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
|
|
import * as grpc from "grpc";
|
|
import * as log from "../log";
|
|
import { ID, Input, Inputs, Output, Resource, ResourceOptions, URN } from "../resource";
|
|
import { debuggablePromise, errorString } from "./debuggable";
|
|
import {
|
|
deserializeProperties,
|
|
deserializeProperty,
|
|
OutputResolvers,
|
|
resolveProperties,
|
|
serializeProperties,
|
|
serializeProperty,
|
|
serializeResourceProperties,
|
|
transferProperties,
|
|
unknownValue,
|
|
} from "./rpc";
|
|
import { excessiveDebugOutput, getMonitor, rpcKeepAlive, serialize } from "./settings";
|
|
|
|
const gstruct = require("google-protobuf/google/protobuf/struct_pb.js");
|
|
const resproto = require("../proto/resource_pb.js");
|
|
|
|
interface ResourceResolverOperation {
|
|
// A resolver for a resource's URN.
|
|
resolveURN: (urn: URN) => void;
|
|
// A resolver for a resource's ID (for custom resources only).
|
|
resolveID: ((v: ID, performApply: boolean) => void) | undefined;
|
|
// A collection of resolvers for a resource's properties.
|
|
resolvers: OutputResolvers;
|
|
// A parent URN, fully resolved, if any.
|
|
parentURN: URN | undefined;
|
|
// A provider reference, fully resolved, if any.
|
|
providerRef: string | undefined;
|
|
// All serialized properties, fully awaited, serialized, and ready to go.
|
|
serializedProps: Record<string, any>;
|
|
// A set of dependency URNs that this resource is dependent upon (both implicitly and explicitly).
|
|
dependencies: Set<URN>;
|
|
}
|
|
|
|
/**
|
|
* Reads an existing custom resource's state from the resource monitor. Note that resources read in this way
|
|
* will not be part of the resulting stack's state, as they are presumed to belong to another.
|
|
*/
|
|
export function readResource(res: Resource, t: string, name: string, props: Inputs, opts: ResourceOptions): void {
|
|
const id: Input<ID> | undefined = opts.id;
|
|
if (!id) {
|
|
throw new Error("Cannot read resource whose options are lacking an ID value");
|
|
}
|
|
|
|
const label = `resource:${name}[${t}]#...`;
|
|
log.debug(`Reading resource: id=${id}, t=${t}, name=${name}`);
|
|
|
|
const monitor: any = getMonitor();
|
|
const resopAsync = prepareResource(label, res, true, props, opts);
|
|
debuggablePromise(resopAsync.then(async (resop) => {
|
|
const resolvedID = await serializeProperty(label, id, []);
|
|
log.debug(`ReadResource RPC prepared: id=${resolvedID}, t=${t}, name=${name}` +
|
|
(excessiveDebugOutput ? `, obj=${JSON.stringify(resop.serializedProps)}` : ``));
|
|
|
|
// Create a resource request and do the RPC.
|
|
const req = new resproto.ReadResourceRequest();
|
|
req.setType(t);
|
|
req.setName(name);
|
|
req.setId(resolvedID);
|
|
req.setParent(resop.parentURN);
|
|
req.setProvider(resop.providerRef);
|
|
req.setProperties(gstruct.Struct.fromJavaScript(resop.serializedProps));
|
|
req.setDependenciesList(Array.from(resop.dependencies));
|
|
|
|
// Now run the operation, serializing the invocation if necessary.
|
|
const opLabel = `monitor.readResource(${label})`;
|
|
runAsyncResourceOp(opLabel, async () => {
|
|
const resp: any = await debuggablePromise(new Promise((resolve, reject) =>
|
|
monitor.readResource(req, (err: Error, innerResponse: any) => {
|
|
log.debug(`ReadResource RPC finished: ${label}; err: ${err}, resp: ${innerResponse}`);
|
|
if (err) {
|
|
log.error(`Failed to read resource #${resolvedID} '${name}' [${t}]: ${err.stack}`);
|
|
reject(err);
|
|
}
|
|
else {
|
|
resolve(innerResponse);
|
|
}
|
|
})), opLabel);
|
|
|
|
// Now resolve everything: the URN, the ID (supplied as input), and the output properties.
|
|
resop.resolveURN(resp.getUrn());
|
|
resop.resolveID!(resolvedID, resolvedID !== undefined);
|
|
await resolveOutputs(res, t, name, props, resp.getProperties(), resop.resolvers);
|
|
});
|
|
}));
|
|
}
|
|
|
|
/**
|
|
* registerResource registers a new resource object with a given type t and name. It returns the auto-generated
|
|
* URN and the ID that will resolve after the deployment has completed. All properties will be initialized to property
|
|
* objects that the registration operation will resolve at the right time (or remain unresolved for deployments).
|
|
*/
|
|
export function registerResource(res: Resource, t: string, name: string, custom: boolean,
|
|
props: Inputs, opts: ResourceOptions): void {
|
|
const label = `resource:${name}[${t}]`;
|
|
log.debug(`Registering resource: t=${t}, name=${name}, custom=${custom}`);
|
|
|
|
const monitor: any = getMonitor();
|
|
const resopAsync = prepareResource(label, res, custom, props, opts);
|
|
debuggablePromise(resopAsync.then(async (resop) => {
|
|
log.debug(`RegisterResource RPC prepared: t=${t}, name=${name}` +
|
|
(excessiveDebugOutput ? `, obj=${JSON.stringify(resop.serializedProps)}` : ``));
|
|
|
|
const req = new resproto.RegisterResourceRequest();
|
|
req.setType(t);
|
|
req.setName(name);
|
|
req.setParent(resop.parentURN);
|
|
req.setCustom(custom);
|
|
req.setObject(gstruct.Struct.fromJavaScript(resop.serializedProps));
|
|
req.setProtect(opts.protect);
|
|
req.setProvider(resop.providerRef);
|
|
req.setDependenciesList(Array.from(resop.dependencies));
|
|
|
|
// Now run the operation, serializing the invocation if necessary.
|
|
const opLabel = `monitor.registerResource(${label})`;
|
|
runAsyncResourceOp(opLabel, async () => {
|
|
const resp: any = await debuggablePromise(new Promise((resolve, reject) =>
|
|
monitor.registerResource(req, (err: grpc.ServiceError, innerResponse: any) => {
|
|
log.debug(`RegisterResource RPC finished: ${label}; err: ${err}, resp: ${innerResponse}`);
|
|
if (err) {
|
|
// If the monitor is unavailable, it is in the process of shutting down or has already
|
|
// shut down. Don't emit an error and don't do any more RPCs.
|
|
if (err.code === grpc.status.UNAVAILABLE) {
|
|
log.debug("Resource monitor is terminating");
|
|
waitForDeath();
|
|
}
|
|
|
|
log.error(`Failed to register new resource '${name}' [${t}]: ${err.stack}`);
|
|
reject(err);
|
|
}
|
|
else {
|
|
resolve(innerResponse);
|
|
}
|
|
})), opLabel);
|
|
|
|
resop.resolveURN(resp.getUrn());
|
|
|
|
// Note: 'id || undefined' is intentional. We intentionally collapse falsy values to
|
|
// undefined so that later parts of our system don't have to deal with values like 'null'.
|
|
if (resop.resolveID) {
|
|
const id = resp.getId() || undefined;
|
|
resop.resolveID(id, id !== undefined);
|
|
}
|
|
|
|
// Now resolve the output properties.
|
|
await resolveOutputs(res, t, name, props, resp.getObject(), resop.resolvers);
|
|
});
|
|
}));
|
|
}
|
|
|
|
/**
|
|
* Prepares for an RPC that will manufacture a resource, and hence deals with input and output properties.
|
|
*/
|
|
async function prepareResource(label: string, res: Resource, custom: boolean,
|
|
props: Inputs, opts: ResourceOptions): Promise<ResourceResolverOperation> {
|
|
// Simply initialize the URN property and get prepared to resolve it later on.
|
|
// Note: a resource urn will always get a value, and thus the output property
|
|
// for it can always run .apply calls.
|
|
let resolveURN: (urn: URN) => void;
|
|
(res as any).urn = Output.create(
|
|
res,
|
|
debuggablePromise(
|
|
new Promise<URN>(resolve => resolveURN = resolve),
|
|
`resolveURN(${label})`),
|
|
/*performApply:*/ Promise.resolve(true));
|
|
|
|
// If a custom resource, make room for the ID property.
|
|
let resolveID: ((v: any, performApply: boolean) => void) | undefined;
|
|
if (custom) {
|
|
let resolveValue: (v: ID) => void;
|
|
let resolvePerformApply: (v: boolean) => void;
|
|
(res as any).id = Output.create(
|
|
res,
|
|
debuggablePromise(new Promise<ID>(resolve => resolveValue = resolve), `resolveID(${label})`),
|
|
debuggablePromise(new Promise<boolean>(
|
|
resolve => resolvePerformApply = resolve), `resolveIDPerformApply(${label})`));
|
|
|
|
resolveID = (v, performApply) => {
|
|
resolveValue(v);
|
|
resolvePerformApply(performApply);
|
|
};
|
|
}
|
|
|
|
// Now "transfer" all input properties into unresolved Promises on res. This way,
|
|
// this resource will look like it has all its output properties to anyone it is
|
|
// passed to. However, those promises won't actually resolve until the registerResource
|
|
// RPC returns
|
|
const resolvers = transferProperties(res, label, props);
|
|
|
|
/** IMPORTANT! We should never await prior to this line, otherwise the Resource will be partly uninitialized. */
|
|
|
|
// Before we can proceed, all our dependencies must be finished.
|
|
let dependsOn: Resource[] = [];
|
|
if (Array.isArray(opts.dependsOn)) {
|
|
dependsOn = opts.dependsOn;
|
|
} else if (opts.dependsOn) {
|
|
dependsOn = [opts.dependsOn];
|
|
}
|
|
const explicitURNDeps = await debuggablePromise(
|
|
Promise.all(dependsOn.map(d => d.urn.promise())), `dependsOn(${label})`);
|
|
|
|
// Serialize out all our props to their final values. In doing so, we'll also collect all
|
|
// the Resources pointed to by any Dependency objects we encounter, adding them to 'propertyDependencies'.
|
|
const implicitDependencies: Resource[] = [];
|
|
const serializedProps = await serializeResourceProperties(label, props, implicitDependencies);
|
|
|
|
let parentURN: URN | undefined;
|
|
if (opts.parent) {
|
|
parentURN = await opts.parent.urn.promise();
|
|
}
|
|
|
|
let providerRef: string | undefined;
|
|
if (opts.provider) {
|
|
const providerURN = await opts.provider.urn.promise();
|
|
const providerID = await opts.provider.id.promise() || unknownValue;
|
|
providerRef = `${providerURN}::${providerID}`;
|
|
}
|
|
|
|
const dependencies: Set<URN> = new Set<URN>(explicitURNDeps);
|
|
for (const implicitDep of implicitDependencies) {
|
|
dependencies.add(await implicitDep.urn.promise());
|
|
}
|
|
|
|
return {
|
|
resolveURN: resolveURN!,
|
|
resolveID: resolveID,
|
|
resolvers: resolvers,
|
|
serializedProps: serializedProps,
|
|
parentURN: parentURN,
|
|
providerRef: providerRef,
|
|
dependencies: dependencies,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Finishes a resource creation RPC operation by resolving its outputs to the resulting RPC payload.
|
|
*/
|
|
async function resolveOutputs(res: Resource, t: string, name: string,
|
|
props: Inputs, outputs: any, resolvers: OutputResolvers): Promise<void> {
|
|
// Produce a combined set of property states, starting with inputs and then applying
|
|
// outputs. If the same property exists in the inputs and outputs states, the output wins.
|
|
const allProps: Record<string, any> = {};
|
|
if (outputs) {
|
|
Object.assign(allProps, deserializeProperties(outputs));
|
|
}
|
|
|
|
const label = `resource:${name}[${t}]#...`;
|
|
for (const key of Object.keys(props)) {
|
|
if (!allProps.hasOwnProperty(key)) {
|
|
// input prop the engine didn't give us a final value for. Just use the value passed into the resource
|
|
// after round-tripping it through serialization. We do the round-tripping primarily s.t. we ensure that
|
|
// Output values are handled properly w.r.t. unknowns.
|
|
const inputProp = await serializeProperty(label, props[key], []);
|
|
if (inputProp === undefined) {
|
|
continue;
|
|
}
|
|
allProps[key] = deserializeProperty(inputProp);
|
|
}
|
|
}
|
|
|
|
resolveProperties(res, resolvers, t, name, allProps);
|
|
}
|
|
|
|
/**
|
|
* registerResourceOutputs completes the resource registration, attaching an optional set of computed outputs.
|
|
*/
|
|
export function registerResourceOutputs(res: Resource, outputs: Inputs) {
|
|
// Now run the operation. Note that we explicitly do not serialize output registration with
|
|
// respect to other resource operations, as outputs may depend on properties of other resources
|
|
// that will not resolve until later turns. This would create a circular promise chain that can
|
|
// never resolve.
|
|
const opLabel = `monitor.registerResourceOutputs(...)`;
|
|
runAsyncResourceOp(opLabel, async () => {
|
|
// The registration could very well still be taking place, so we will need to wait for its
|
|
// URN. Additionally, the output properties might have come from other resources, so we
|
|
// must await those too.
|
|
const urn = await res.urn.promise();
|
|
const outputsObj = gstruct.Struct.fromJavaScript(
|
|
await serializeProperties(`completeResource`, outputs));
|
|
log.debug(`RegisterResourceOutputs RPC prepared: urn=${urn}` +
|
|
(excessiveDebugOutput ? `, outputs=${JSON.stringify(outputsObj)}` : ``));
|
|
|
|
// Fetch the monitor and make an RPC request.
|
|
const monitor: any = getMonitor();
|
|
|
|
const req = new resproto.RegisterResourceOutputsRequest();
|
|
req.setUrn(urn);
|
|
req.setOutputs(outputsObj);
|
|
|
|
await debuggablePromise(new Promise((resolve, reject) =>
|
|
monitor.registerResourceOutputs(req, (err: grpc.ServiceError, innerResponse: any) => {
|
|
log.debug(`RegisterResourceOutputs RPC finished: urn=${urn}; `+
|
|
`err: ${err}, resp: ${innerResponse}`);
|
|
if (err) {
|
|
// If the monitor is unavailable, it is in the process of shutting down or has already
|
|
// shut down. Don't emit an error and don't do any more RPCs.
|
|
if (err.code === grpc.status.UNAVAILABLE) {
|
|
log.debug("Resource monitor is terminating");
|
|
waitForDeath();
|
|
}
|
|
|
|
log.error(`Failed to end new resource registration '${urn}': ${err.stack}`);
|
|
reject(err);
|
|
}
|
|
else {
|
|
resolve();
|
|
}
|
|
})), opLabel);
|
|
}, false);
|
|
}
|
|
|
|
/**
|
|
* resourceChain is used to serialize all resource requests. If we don't do this, all resource operations will be
|
|
* entirely asynchronous, meaning the dataflow graph that results will determine ordering of operations. This
|
|
* causes problems with some resource providers, so for now we will serialize all of them. The issue
|
|
* pulumi/pulumi#335 tracks coming up with a long-term solution here.
|
|
*/
|
|
let resourceChain: Promise<void> = Promise.resolve();
|
|
let resourceChainLabel: string | undefined = undefined;
|
|
|
|
// runAsyncResourceOp runs an asynchronous resource operation, possibly serializing it as necessary.
|
|
function runAsyncResourceOp(label: string, callback: () => Promise<void>, serial?: boolean): void {
|
|
// Serialize the invocation if necessary.
|
|
if (serial === undefined) {
|
|
serial = serialize();
|
|
}
|
|
const resourceOp: Promise<void> = debuggablePromise(resourceChain.then(async () => {
|
|
if (serial) {
|
|
resourceChainLabel = label;
|
|
log.debug(`Resource RPC serialization requested: ${label} is current`);
|
|
}
|
|
return callback();
|
|
}));
|
|
|
|
// Ensure the process won't exit until this RPC call finishes and resolve it when appropriate.
|
|
const done: () => void = rpcKeepAlive();
|
|
const finalOp: Promise<void> = debuggablePromise(resourceOp.then(() => { done(); }, () => { done(); }));
|
|
|
|
// Set up another promise that propagates the error, if any, so that it triggers unhandled rejection logic.
|
|
resourceOp.catch((err) => Promise.reject(err));
|
|
|
|
// If serialization is requested, wait for the prior resource operation to finish before we proceed, serializing
|
|
// them, and make this the current resource operation so that everybody piles up on it.
|
|
if (serial) {
|
|
resourceChain = finalOp;
|
|
if (resourceChainLabel) {
|
|
log.debug(`Resource RPC serialization requested: ${label} is behind ${resourceChainLabel}`);
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* waitForDeath loops forever. This is a hack.
|
|
*
|
|
* The purpose of this hack is to deal with graceful termination of the resource monitor.
|
|
* When the engine decides that it needs to terminate, it shuts down the Log and ResourceMonitor RPC
|
|
* endpoints. Shutting down RPC endpoints involves draining all outstanding RPCs and denying new connections.
|
|
*
|
|
* This is all fine for us as the language host, but we need to 1) not let the RPC that just failed due to
|
|
* the ResourceMonitor server shutdown get displayed as an error and 2) not do any more RPCs, since they'll fail.
|
|
*
|
|
* We can accomplish both by just doing nothing until the engine kills us. It's ugly, but it works.
|
|
*/
|
|
function waitForDeath(): never {
|
|
// tslint:disable-next-line
|
|
while (true) {}
|
|
}
|