2022-07-20 21:38:55 +00:00
|
|
|
// Copyright 2016-2022, Pulumi Corporation.
|
2018-05-22 19:43:36 +00:00
|
|
|
//
|
|
|
|
// 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.
|
2017-10-14 00:48:54 +00:00
|
|
|
|
2023-06-29 22:28:31 +00:00
|
|
|
import { Inputs, Input, Output } from "../output";
|
2017-11-17 02:21:41 +00:00
|
|
|
import * as resource from "../resource";
|
2022-07-20 21:38:55 +00:00
|
|
|
import * as settings from "../runtime/settings";
|
|
|
|
import * as serializeClosure from "../runtime/closure/serializeClosure";
|
|
|
|
|
2017-10-14 00:48:54 +00:00
|
|
|
/**
|
2017-10-14 21:29:49 +00:00
|
|
|
* CheckResult represents the results of a call to `ResourceProvider.check`.
|
2017-10-14 00:48:54 +00:00
|
|
|
*/
|
2023-01-17 17:55:36 +00:00
|
|
|
export interface CheckResult<Inputs = any> {
|
2017-10-14 00:48:54 +00:00
|
|
|
/**
|
2017-12-03 00:34:16 +00:00
|
|
|
* The inputs to use, if any.
|
2017-10-14 00:48:54 +00:00
|
|
|
*/
|
2023-01-17 17:55:36 +00:00
|
|
|
readonly inputs?: Inputs;
|
2017-10-14 00:48:54 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Any validation failures that occurred.
|
|
|
|
*/
|
2017-12-06 03:14:28 +00:00
|
|
|
readonly failures?: CheckFailure[];
|
2017-10-14 00:48:54 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
2017-10-14 21:29:49 +00:00
|
|
|
* CheckFailure represents a single failure in the results of a call to `ResourceProvider.check`
|
2017-10-14 00:48:54 +00:00
|
|
|
*/
|
2017-12-06 03:14:28 +00:00
|
|
|
export interface CheckFailure {
|
2017-10-14 00:48:54 +00:00
|
|
|
/**
|
|
|
|
* The property that failed validation.
|
|
|
|
*/
|
2017-12-06 03:14:28 +00:00
|
|
|
readonly property: string;
|
2017-10-14 00:48:54 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* The reason that the property failed validation.
|
|
|
|
*/
|
2017-12-06 03:14:28 +00:00
|
|
|
readonly reason: string;
|
2017-10-14 00:48:54 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
2017-10-14 21:29:49 +00:00
|
|
|
* DiffResult represents the results of a call to `ResourceProvider.diff`.
|
2017-10-14 00:48:54 +00:00
|
|
|
*/
|
2017-12-06 03:14:28 +00:00
|
|
|
export interface DiffResult {
|
2018-04-05 14:00:16 +00:00
|
|
|
/**
|
|
|
|
* If true, this diff detected changes and suggests an update.
|
|
|
|
*/
|
|
|
|
readonly changes?: boolean;
|
|
|
|
|
2017-10-14 00:48:54 +00:00
|
|
|
/**
|
|
|
|
* If this update requires a replacement, the set of properties triggering it.
|
|
|
|
*/
|
2017-12-06 03:14:28 +00:00
|
|
|
readonly replaces?: string[];
|
2017-10-14 00:48:54 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* An optional list of properties that will not ever change.
|
|
|
|
*/
|
2017-12-06 03:14:28 +00:00
|
|
|
readonly stables?: string[];
|
2017-12-11 17:22:04 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* If true, and a replacement occurs, the resource will first be deleted before being recreated. This is to
|
|
|
|
* void potential side-by-side issues with the default create before delete behavior.
|
|
|
|
*/
|
|
|
|
readonly deleteBeforeReplace?: boolean;
|
2017-10-14 00:48:54 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
2017-10-14 21:29:49 +00:00
|
|
|
* CreateResult represents the results of a call to `ResourceProvider.create`.
|
2017-10-14 00:48:54 +00:00
|
|
|
*/
|
2023-01-17 17:55:36 +00:00
|
|
|
export interface CreateResult<Outputs = any> {
|
2017-10-14 00:48:54 +00:00
|
|
|
/**
|
|
|
|
* The ID of the created resource.
|
|
|
|
*/
|
2017-12-06 03:14:28 +00:00
|
|
|
readonly id: resource.ID;
|
2017-10-14 00:48:54 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Any properties that were computed during creation.
|
|
|
|
*/
|
2023-01-17 17:55:36 +00:00
|
|
|
readonly outs?: Outputs;
|
2017-10-14 00:48:54 +00:00
|
|
|
}
|
|
|
|
|
2023-01-17 17:55:36 +00:00
|
|
|
export interface ReadResult<Outputs = any> {
|
2018-08-23 00:52:46 +00:00
|
|
|
/**
|
|
|
|
* The ID of the resource ready back (or blank if missing).
|
|
|
|
*/
|
|
|
|
readonly id?: resource.ID;
|
2018-04-05 14:00:16 +00:00
|
|
|
/**
|
|
|
|
* The current property state read from the live environment.
|
|
|
|
*/
|
2023-01-17 17:55:36 +00:00
|
|
|
readonly props?: Outputs;
|
2018-04-05 14:00:16 +00:00
|
|
|
}
|
|
|
|
|
2017-10-14 00:48:54 +00:00
|
|
|
/**
|
2017-10-14 21:29:49 +00:00
|
|
|
* UpdateResult represents the results of a call to `ResourceProvider.update`.
|
2017-10-14 00:48:54 +00:00
|
|
|
*/
|
2023-01-17 17:55:36 +00:00
|
|
|
export interface UpdateResult<Outputs = any> {
|
2017-10-14 00:48:54 +00:00
|
|
|
/**
|
|
|
|
* Any properties that were computed during updating.
|
|
|
|
*/
|
2023-01-17 17:55:36 +00:00
|
|
|
readonly outs?: Outputs;
|
2017-10-14 00:48:54 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
2017-10-14 21:29:49 +00:00
|
|
|
* ResourceProvider represents an object that provides CRUD operations for a particular type of resource.
|
2017-10-14 00:48:54 +00:00
|
|
|
*/
|
2023-01-17 17:55:36 +00:00
|
|
|
export interface ResourceProvider<Inputs = any, Outputs = any> {
|
2017-10-14 00:48:54 +00:00
|
|
|
/**
|
|
|
|
* Check validates that the given property bag is valid for a resource of the given type.
|
|
|
|
*
|
2017-12-03 00:34:16 +00:00
|
|
|
* @param olds The old input properties to use for validation.
|
|
|
|
* @param news The new input properties to use for validation.
|
2017-10-14 00:48:54 +00:00
|
|
|
*/
|
2023-01-17 17:55:36 +00:00
|
|
|
check?: (olds: Inputs, news: Inputs) => Promise<CheckResult<Inputs>>;
|
2017-10-14 00:48:54 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Diff checks what impacts a hypothetical update will have on the resource's properties.
|
|
|
|
*
|
|
|
|
* @param id The ID of the resource to diff.
|
|
|
|
* @param olds The old values of properties to diff.
|
|
|
|
* @param news The new values of properties to diff.
|
|
|
|
*/
|
2023-01-17 17:55:36 +00:00
|
|
|
diff?: (id: resource.ID, olds: Outputs, news: Inputs) => Promise<DiffResult>;
|
2017-10-14 00:48:54 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Create allocates a new instance of the provided resource and returns its unique ID afterwards.
|
2020-01-13 18:45:07 +00:00
|
|
|
* If this call fails, the resource must not have been created (i.e., it is "transactional").
|
2017-10-14 00:48:54 +00:00
|
|
|
*
|
|
|
|
* @param inputs The properties to set during creation.
|
|
|
|
*/
|
2023-01-17 17:55:36 +00:00
|
|
|
create: (inputs: Inputs) => Promise<CreateResult<Outputs>>;
|
2017-10-14 00:48:54 +00:00
|
|
|
|
2018-04-05 14:00:16 +00:00
|
|
|
/**
|
|
|
|
* Reads the current live state associated with a resource. Enough state must be included in the inputs to uniquely
|
|
|
|
* identify the resource; this is typically just the resource ID, but it may also include some properties.
|
|
|
|
*/
|
2023-01-17 17:55:36 +00:00
|
|
|
read?: (id: resource.ID, props?: Outputs) => Promise<ReadResult<Outputs>>;
|
2018-04-05 14:00:16 +00:00
|
|
|
|
2017-10-14 00:48:54 +00:00
|
|
|
/**
|
|
|
|
* Update updates an existing resource with new values.
|
|
|
|
*
|
|
|
|
* @param id The ID of the resource to update.
|
|
|
|
* @param olds The old values of properties to update.
|
|
|
|
* @param news The new values of properties to update.
|
|
|
|
*/
|
2023-01-17 17:55:36 +00:00
|
|
|
update?: (id: resource.ID, olds: Outputs, news: Inputs) => Promise<UpdateResult<Outputs>>;
|
2017-10-14 00:48:54 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Delete tears down an existing resource with the given ID. If it fails, the resource is assumed to still exist.
|
|
|
|
*
|
|
|
|
* @param id The ID of the resource to delete.
|
|
|
|
* @param props The current properties on the resource.
|
|
|
|
*/
|
2023-01-17 17:55:36 +00:00
|
|
|
delete?: (id: resource.ID, props: Outputs) => Promise<void>;
|
2017-10-14 00:48:54 +00:00
|
|
|
}
|
2017-10-16 20:01:13 +00:00
|
|
|
|
2023-06-29 22:28:31 +00:00
|
|
|
const providerCache = new WeakMap<ResourceProvider, Input<string>>();
|
2021-04-05 21:37:45 +00:00
|
|
|
|
2023-06-29 22:28:31 +00:00
|
|
|
function serializeProvider(provider: ResourceProvider): Input<string> {
|
|
|
|
let result: Input<string>;
|
2021-04-05 23:03:28 +00:00
|
|
|
// caching is enabled by default as of 3.0
|
2022-07-20 21:38:55 +00:00
|
|
|
if (settings.cacheDynamicProviders()) {
|
2021-04-05 21:37:45 +00:00
|
|
|
const cachedProvider = providerCache.get(provider);
|
|
|
|
if (cachedProvider) {
|
|
|
|
result = cachedProvider;
|
|
|
|
} else {
|
2023-06-29 22:28:31 +00:00
|
|
|
result = serializeFunctionMaybeSecret(provider);
|
2021-04-05 21:37:45 +00:00
|
|
|
providerCache.set(provider, result);
|
|
|
|
}
|
|
|
|
} else {
|
2023-06-29 22:28:31 +00:00
|
|
|
result = serializeFunctionMaybeSecret(provider);
|
2021-04-05 21:37:45 +00:00
|
|
|
}
|
|
|
|
return result;
|
2017-10-15 23:18:17 +00:00
|
|
|
}
|
2017-10-14 00:48:54 +00:00
|
|
|
|
2023-06-29 22:28:31 +00:00
|
|
|
function serializeFunctionMaybeSecret(provider: ResourceProvider): Output<string> {
|
|
|
|
// Load runtime/closure on demand, as its dependencies are slow to load.
|
|
|
|
//
|
|
|
|
// See https://www.typescriptlang.org/docs/handbook/modules.html#optional-module-loading-and-other-advanced-loading-scenarios
|
|
|
|
const sc: typeof serializeClosure = require("../runtime/closure/serializeClosure");
|
|
|
|
|
|
|
|
const sfPromise = sc.serializeFunction(() => provider, { allowSecrets: true });
|
|
|
|
|
|
|
|
// Create an Output from the promise's text and containsSecrets properties. Uses the internal API since we don't provide a public interface for this.
|
|
|
|
return new Output(
|
|
|
|
[],
|
|
|
|
sfPromise.then((sf) => sf.text),
|
|
|
|
new Promise((resolve) => resolve(true)),
|
|
|
|
sfPromise.then((sf) => sf.containsSecrets),
|
|
|
|
new Promise((resolve) => resolve([])),
|
|
|
|
);
|
|
|
|
}
|
|
|
|
|
2017-10-14 21:29:49 +00:00
|
|
|
/**
|
|
|
|
* Resource represents a Pulumi Resource that incorporates an inline implementation of the Resource's CRUD operations.
|
|
|
|
*/
|
2017-10-15 23:18:17 +00:00
|
|
|
export abstract class Resource extends resource.CustomResource {
|
2017-10-14 21:29:49 +00:00
|
|
|
/**
|
|
|
|
* Creates a new dynamic resource.
|
|
|
|
*
|
|
|
|
* @param provider The implementation of the resource's CRUD operations.
|
|
|
|
* @param name The name of the resource.
|
|
|
|
* @param props The arguments to use to populate the new resource. Must not define the reserved
|
|
|
|
* property "__provider".
|
Implement resource protection (#751)
This change implements resource protection, as per pulumi/pulumi#689.
The overall idea is that a resource can be marked as "protect: true",
which will prevent deletion of that resource for any reason whatsoever
(straight deletion, replacement, etc). This is expressed in the
program. To "unprotect" a resource, one must perform an update setting
"protect: false", and then afterwards, they can delete the resource.
For example:
let res = new MyResource("precious", { .. }, { protect: true });
Afterwards, the resource will display in the CLI with a lock icon, and
any attempts to remove it will fail in the usual ways (in planning or,
worst case, during an actual update).
This was done by adding a new ResourceOptions bag parameter to the
base Resource types. This is unfortunately a breaking change, but now
is the right time to take this one. We had been adding new settings
one by one -- like parent and dependsOn -- and this new approach will
set us up to add any number of additional settings down the road,
without needing to worry about breaking anything ever again.
This is related to protected stacks, as described in
pulumi/pulumi-service#399. Most likely this will serve as a foundational
building block that enables the coarser grained policy management.
2017-12-20 22:31:07 +00:00
|
|
|
* @param opts A bag of options that control this resource's behavior.
|
2023-01-13 23:58:49 +00:00
|
|
|
* @param module The module of the resource.
|
|
|
|
* @param type The type of the resource.
|
2017-10-14 21:29:49 +00:00
|
|
|
*/
|
2023-04-28 22:27:10 +00:00
|
|
|
constructor(
|
|
|
|
provider: ResourceProvider,
|
|
|
|
name: string,
|
|
|
|
props: Inputs,
|
|
|
|
opts?: resource.CustomResourceOptions,
|
|
|
|
module?: string,
|
|
|
|
type: string = "Resource",
|
|
|
|
) {
|
2017-10-14 21:29:49 +00:00
|
|
|
const providerKey: string = "__provider";
|
|
|
|
if (props[providerKey]) {
|
|
|
|
throw new Error("A dynamic resource must not define the __provider key");
|
|
|
|
}
|
2017-10-15 23:18:17 +00:00
|
|
|
props[providerKey] = serializeProvider(provider);
|
2017-10-14 21:29:49 +00:00
|
|
|
|
2023-01-13 23:58:49 +00:00
|
|
|
super(`pulumi-nodejs:dynamic${module ? `/${module}` : ""}:${type}`, name, props, opts);
|
2017-10-14 00:48:54 +00:00
|
|
|
}
|
|
|
|
}
|