@causa/workspace-google 1.3.1 → 1.4.0-beta.2

package/dist/graph/cloud-run.d.ts

@@ -0,0 +1,98 @@
+import type { ServiceContainerConfiguration } from '@causa/workspace-core';
+import { GraphExtractionFact, type GraphContext, type GraphFactOutput, type GraphTemplatePart, type WorkspaceProject } from '@causa/workspace-core/graph';
+import { type TerraformModuleBlock } from '@causa/workspace-terraform';
+/**
+ * A trigger defined in the `serviceContainer.triggers` configuration.
+ */
+type ServiceContainerTrigger = NonNullable<NonNullable<ServiceContainerConfiguration['serviceContainer']>['triggers']>[string];
+/**
+ * The source of the Causa Terraform module deploying a service container to Cloud Run.
+ */
+export declare const CLOUD_RUN_MODULE_SOURCE = "causa-io/service-container-cloud-run/google";
+/**
+ * A block of the Cloud Run module, i.e. a deployed service, with the module's logic evaluated from the block's
+ * arguments and the project's configuration.
+ */
+export type CloudRunService = {
+    /**
+     * The Terraform module block defining the Cloud Run service.
+     */
+    readonly block: TerraformModuleBlock;
+    /**
+     * The project whose configuration file the block reads.
+     */
+    readonly project: WorkspaceProject;
+    /**
+     * The name of the service, `coalesce(var.name, project.name)`.
+     */
+    readonly name: string;
+    /**
+     * The ID of the `service` node.
+     */
+    readonly id: string;
+    /**
+     * Whether the service's HTTP endpoints are exposed through the API router (`enable_public_http_endpoints`, `false` by
+     * default).
+     */
+    readonly enablePublicHttpEndpoints: boolean;
+    /**
+     * Whether the block grants the publisher role on the project's `outputs.eventTopics` (`set_pubsub_permissions`,
+     * defaulting to `set_iam_permissions`).
+     */
+    readonly setPubsubPermissions: boolean;
+    /**
+     * Whether the block grants access to the Spanner databases of the project's outputs (`set_spanner_permissions`,
+     * defaulting to `set_iam_permissions`).
+     */
+    readonly setSpannerPermissions: boolean;
+    /**
+     * Whether the block grants access to the Firestore database for the collections of the project's outputs
+     * (`set_firestore_permissions`, defaulting to `set_iam_permissions`).
+     */
+    readonly setFirestorePermissions: boolean;
+    /**
+     * Whether the block grants the enqueuer role on the queues of the project's task triggers (`set_tasks_permissions`,
+     * defaulting to `set_iam_permissions`).
+     */
+    readonly setTasksPermissions: boolean;
+    /**
+     * The triggers the module turns into Pub/Sub push subscriptions, keyed by name: `event` or `google.pubSub` triggers
+     * with an HTTP endpoint, not disabled.
+     */
+    readonly pubsubTriggers: ReadonlyMap<string, ServiceContainerTrigger>;
+    /**
+     * The triggers the module turns into Cloud Tasks queues, keyed by name. A disabled trigger still has its * queue,
+     * paused.
+     */
+    readonly tasksTriggers: ReadonlyMap<string, ServiceContainerTrigger>;
+    /**
+     * The triggers the module turns into Cloud Scheduler jobs, keyed by name. A disabled trigger still has its job,
+     * paused.
+     */
+    readonly cronTriggers: ReadonlyMap<string, ServiceContainerTrigger>;
+    /**
+     * The GCP project part of resource names.
+     */
+    readonly projectPart: GraphTemplatePart;
+    /**
+     * The location part of resource names, shared by the service, its queues, and its jobs.
+     */
+    readonly locationPart: GraphTemplatePart;
+};
+/**
+ * The blocks of the Cloud Run module, evaluated against the configuration of the projects they deploy.
+ * Blocks whose `configuration_file` does not name a project of the workspace cannot be mirrored, and are reported.
+ */
+export declare class CloudRunFact extends GraphExtractionFact<CloudRunService[]> {
+    compute(graph: GraphContext): Promise<GraphFactOutput<CloudRunService[]>>;
+    /**
+     * Evaluates a Cloud Run module block, mirroring the defaults of the module.
+     *
+     * @param block The module block.
+     * @param project The project whose configuration file the block reads.
+     * @param warnings The warnings of the fact, to which the ones about the block are added.
+     * @returns The {@link CloudRunService}.
+     */
+    private evaluate;
+}
+export {};

package/dist/graph/cloud-run.js

@@ -0,0 +1,102 @@
+import { GraphExtractionFact, ProjectsFact, serviceId, } from '@causa/workspace-core/graph';
+import { modulesWithSource, TerraformProjectsFact, } from '@causa/workspace-terraform';
+import { argumentOrConfiguration, projectOfConfigurationFile, } from './terraform-modules.js';
+/**
+ * The source of the Causa Terraform module deploying a service container to Cloud Run.
+ */
+export const CLOUD_RUN_MODULE_SOURCE = 'causa-io/service-container-cloud-run/google';
+/**
+ * The major version of the Cloud Run module whose behavior is mirrored (trigger filters, IAM grants, resource names).
+ */
+const MIRRORED_CLOUD_RUN_MAJOR = 1;
+/**
+ * The blocks of the Cloud Run module, evaluated against the configuration of the projects they deploy.
+ * Blocks whose `configuration_file` does not name a project of the workspace cannot be mirrored, and are reported.
+ */
+export class CloudRunFact extends GraphExtractionFact {
+    async compute(graph) {
+        const [terraformProjects, projects] = await Promise.all([
+            graph.get(TerraformProjectsFact),
+            graph.get(ProjectsFact),
+        ]);
+        const services = [];
+        const warnings = [];
+        for (const block of modulesWithSource(terraformProjects, CLOUD_RUN_MODULE_SOURCE)) {
+            const project = projectOfConfigurationFile(block.arguments['configuration_file'], projects);
+            if (!project) {
+                warnings.push({
+                    message: "The Cloud Run module block is skipped, as its 'configuration_file' does not name a project of the workspace.",
+                    sources: [block.declaration],
+                });
+                continue;
+            }
+            services.push(this.evaluate(block, project, warnings));
+        }
+        return { value: services, warnings };
+    }
+    /**
+     * Evaluates a Cloud Run module block, mirroring the defaults of the module.
+     *
+     * @param block The module block.
+     * @param project The project whose configuration file the block reads.
+     * @param warnings The warnings of the fact, to which the ones about the block are added.
+     * @returns The {@link CloudRunService}.
+     */
+    evaluate(block, project, warnings) {
+        const sources = [block.declaration];
+        const major = Number(block.version?.split('.')[0]);
+        if (major !== MIRRORED_CLOUD_RUN_MAJOR) {
+            warnings.push({
+                message: `The Cloud Run module version '${block.version ?? 'unset'}' is not the one being mirrored (${MIRRORED_CLOUD_RUN_MAJOR}.x). Resources are extracted as for that version.`,
+                sources,
+            });
+        }
+        const argument = (name, fallback) => {
+            const value = block.arguments[name];
+            if (value === undefined) {
+                return fallback;
+            }
+            if (!('value' in value)) {
+                const assumed = typeof fallback === 'string' ? fallback : JSON.stringify(fallback);
+                warnings.push({
+                    message: `The argument '${name}' is computed (${value.expression}). Assuming ${assumed}.`,
+                    sources,
+                });
+                return fallback;
+            }
+            return (value.value ?? fallback);
+        };
+        const name = argument('name', project.name) || project.name;
+        const enableTriggers = argument('enable_triggers', false);
+        const triggers = Object.entries({
+            ...(project.context
+                .asConfiguration()
+                .get('serviceContainer.triggers', { unsafe: true }) ?? {}),
+            ...argument('triggers', {}),
+        }).filter(([, t]) => t.endpoint?.type === 'http');
+        const ofTypes = (enabled, types, excludeDisabled = false) => new Map(enabled
+            ? triggers.filter(([, t]) => types.includes(t.type ?? '') &&
+                !(excludeDisabled && t.enabled === false))
+            : []);
+        const setIamPermissions = argument('set_iam_permissions', true);
+        return {
+            block,
+            project,
+            name,
+            id: serviceId(project.directory, name),
+            enablePublicHttpEndpoints: argument('enable_public_http_endpoints', false),
+            setPubsubPermissions: argument('set_pubsub_permissions', setIamPermissions),
+            setSpannerPermissions: argument('set_spanner_permissions', setIamPermissions),
+            setFirestorePermissions: argument('set_firestore_permissions', setIamPermissions),
+            setTasksPermissions: argument('set_tasks_permissions', setIamPermissions),
+            pubsubTriggers: ofTypes(argument('enable_pubsub_triggers', enableTriggers), ['event', 'google.pubSub'], true),
+            tasksTriggers: ofTypes(argument('enable_tasks_triggers', enableTriggers), ['task', 'google.task', 'google.tasks']),
+            cronTriggers: ofTypes(argument('enable_cron_triggers', enableTriggers), [
+                'cron',
+                'google.scheduler',
+            ]),
+            projectPart: argumentOrConfiguration(block, 'gcp_project_id', 'google.project', warnings),
+            locationPart: argumentOrConfiguration(block, 'location', 'google.cloudRun.location', warnings),
+        };
+    }
+}

package/dist/graph/environment/fetchers/cloud-monitoring-alerts.d.ts

@@ -0,0 +1,6 @@
+import { type GraphEnvironmentFetcher } from '@causa/workspace-core';
+/**
+ * Reads the alerts open at the end of the evaluation window from Cloud Monitoring, and attaches them to the nodes of
+ * their resources.
+ */
+export declare const googleCloudMonitoringAlerts: GraphEnvironmentFetcher;

package/dist/graph/environment/fetchers/cloud-monitoring-alerts.js

@@ -0,0 +1,106 @@
+import { GraphAlertSeverity, } from '@causa/workspace-core';
+import { alertLabelValue, listOpenAlerts, } from '../monitoring-alerts.js';
+import { MONITORING_RESOURCE_MAPPINGS } from '../monitoring-catalog.js';
+import { findMonitoredNode, prepareMonitoringMapping, readMonitoringResourceKey, } from '../monitoring-mappings.js';
+import { googleResources } from '../resources.js';
+import { consoleUrl } from './console-links.js';
+/**
+ * The severities of alerts, keyed by the severity of their policy.
+ */
+const SEVERITIES = {
+    CRITICAL: GraphAlertSeverity.Critical,
+    ERROR: GraphAlertSeverity.Error,
+    WARNING: GraphAlertSeverity.Warning,
+};
+/**
+ * Converts an alert returned by the Alerts API to a {@link GraphAlert}.
+ *
+ * @param alert The alert.
+ * @param project The GCP project from which the alert was listed.
+ * @returns The alert.
+ */
+function toGraphAlert(alert, project) {
+    const severity = SEVERITIES[alert.policy?.severity ?? ''];
+    const id = alert.name?.split('/').at(-1);
+    return {
+        title: alert.policy?.displayName,
+        ...(severity ? { severity } : {}),
+        openedAt: new Date(alert.openTime),
+        ...(id
+            ? { url: consoleUrl(['monitoring', 'alerting', 'alerts', id], project) }
+            : {}),
+    };
+}
+/**
+ * Describes the resource of an alert in a warning.
+ *
+ * @param resource The resource of the alert.
+ * @returns The description.
+ */
+function describeResource(resource) {
+    if (!resource) {
+        return 'a resource of unknown type';
+    }
+    const labels = Object.entries(resource.labels)
+        .filter(([name]) => name !== 'value' && name !== 'monitored_resource')
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, value]) => `${name}=${value}`);
+    return `the '${resource.type}' resource (${labels.join(', ')})`;
+}
+/**
+ * Reads the alerts open at the end of the evaluation window from Cloud Monitoring, and attaches them to the nodes of
+ * their resources.
+ */
+export const googleCloudMonitoringAlerts = {
+    name: 'googleCloudMonitoringAlerts',
+    description: "The `alerts` open at the end of the evaluation window, read from Cloud Monitoring in the projects of the graph's resources, and attached to the nodes of their resources. Alerts that cannot be attached to a node are added to the environment.",
+    fetch: async (environment) => {
+        const projects = [
+            ...new Set(googleResources(environment).map(({ segments }) => segments.projects)),
+        ]
+            .filter((p) => !!p)
+            .sort();
+        const warnings = [];
+        const listed = await Promise.all(projects.map(async (project) => {
+            try {
+                return await listOpenAlerts(environment.context, project, environment.at);
+            }
+            catch (error) {
+                warnings.push({
+                    message: `Failed to list the alerts in project '${project}': ${error.message ?? error}`,
+                });
+                return [];
+            }
+        }));
+        const alerts = listed.flat();
+        if (alerts.length === 0) {
+            return { warnings };
+        }
+        // Only the mappings that may apply to an alert are prepared, as preparing a mapping may require listing resources,
+        // e.g. the backends of load balancers.
+        const candidates = (await Promise.all(MONITORING_RESOURCE_MAPPINGS.filter((mapping) => alerts.some(({ resource }) => resource?.type === mapping.monitoredResource &&
+            readMonitoringResourceKey(mapping, resource.project, (label) => alertLabelValue(resource, label)))).map((mapping) => prepareMonitoringMapping(environment, mapping)))).filter((m) => !!m);
+        const nodes = {};
+        const unattached = [];
+        for (const { alert, project, resource } of alerts) {
+            const graphAlert = toGraphAlert(alert, project);
+            const { node } = resource
+                ? findMonitoredNode(environment, candidates.filter(({ mapping }) => mapping.monitoredResource === resource.type), resource.project, (label) => alertLabelValue(resource, label))
+                : {};
+            if (node) {
+                nodes[node.id] ??= { alerts: [] };
+                nodes[node.id].alerts.push(graphAlert);
+                continue;
+            }
+            unattached.push(graphAlert);
+            warnings.push({
+                message: `The alert of policy '${graphAlert.title}' on ${describeResource(resource)} could not be attached to a node, and is added to the environment.`,
+            });
+        }
+        return {
+            nodes,
+            ...(unattached.length > 0 ? { alerts: unattached } : {}),
+            warnings,
+        };
+    },
+};

package/dist/graph/environment/fetchers/cloud-monitoring.d.ts

@@ -0,0 +1,5 @@
+import type { GraphEnvironmentFetcher } from '@causa/workspace-core';
+/**
+ * Reads the metrics of nodes from Cloud Monitoring, over the evaluation window.
+ */
+export declare const googleCloudMonitoring: GraphEnvironmentFetcher;

package/dist/graph/environment/fetchers/cloud-monitoring.js

@@ -0,0 +1,13 @@
+import { MONITORING_METRICS } from '../monitoring-catalog.js';
+import { queryPointInTimeMetrics } from '../monitoring-query.js';
+/**
+ * Reads the metrics of nodes from Cloud Monitoring, over the evaluation window.
+ */
+export const googleCloudMonitoring = {
+    name: 'googleCloudMonitoring',
+    description: 'The metrics of Cloud Run services, API routers, Pub/Sub topics and subscriptions, Cloud Tasks queues, and Spanner, Firestore, and BigQuery databases, read from Cloud Monitoring.',
+    fetch: async (environment) => {
+        const { nodes, bucketLayouts, warnings } = await queryPointInTimeMetrics(environment, MONITORING_METRICS);
+        return { nodes, bucketLayouts, warnings };
+    },
+};

package/dist/graph/environment/fetchers/cloud-run.d.ts

@@ -0,0 +1,5 @@
+import type { GraphEnvironmentFetcher } from '@causa/workspace-core';
+/**
+ * Reads the deployments of Cloud Run services.
+ */
+export declare const googleCloudRun: GraphEnvironmentFetcher;

package/dist/graph/environment/fetchers/cloud-run.js

@@ -0,0 +1,88 @@
+import { ServiceDeploymentStatus, } from '@causa/workspace-core';
+import { googleResources } from '../resources.js';
+/**
+ * The deployment status for each state of the `Ready` terminal condition of a Cloud Run service.
+ * States are listed both by name and by number, as clients may return either.
+ */
+const DEPLOYMENT_STATUSES = {
+    CONDITION_PENDING: ServiceDeploymentStatus.Deploying,
+    1: ServiceDeploymentStatus.Deploying,
+    CONDITION_RECONCILING: ServiceDeploymentStatus.Deploying,
+    2: ServiceDeploymentStatus.Deploying,
+    CONDITION_FAILED: ServiceDeploymentStatus.Failed,
+    3: ServiceDeploymentStatus.Failed,
+    CONDITION_SUCCEEDED: ServiceDeploymentStatus.Deployed,
+    4: ServiceDeploymentStatus.Deployed,
+};
+/**
+ * Returns what is deployed for a Cloud Run service.
+ *
+ * @param service The Cloud Run service.
+ * @returns The deployment.
+ */
+function toDeployment(service) {
+    const image = service.template?.containers?.[0]?.image ?? undefined;
+    const updateSeconds = service.updateTime?.seconds;
+    const updatedAt = updateSeconds
+        ? new Date(Number(updateSeconds.toString()) * 1000)
+        : undefined;
+    const { state, message } = service.terminalCondition ?? {};
+    const status = state ? DEPLOYMENT_STATUSES[state] : undefined;
+    return {
+        ...(image ? { image } : {}),
+        ...(updatedAt ? { updatedAt } : {}),
+        ...(status ? { status } : {}),
+        ...(status && message ? { message } : {}),
+    };
+}
+/**
+ * Reads the deployments of Cloud Run services.
+ */
+export const googleCloudRun = {
+    name: 'googleCloudRun',
+    description: 'The `deployment` of services deployed on Cloud Run: the container image, the last update time, and the status of the latest deployment from the `Ready` condition. The deployment is the current one, with a warning when the service was updated after the end of the evaluation window.',
+    fetch: async (environment) => {
+        const services = googleResources(environment, 'run.googleapis.com/Service', 'service');
+        if (services.length === 0) {
+            return {};
+        }
+        const { CloudRunService } = await import('../../../services/cloud-run.js');
+        const { servicesClient } = environment.context.service(CloudRunService);
+        // Calls on a gax client crash the process when credentials cannot be loaded, while `initialize` rejects.
+        await servicesClient.initialize();
+        const byLocation = Map.groupBy(services, ({ segments }) => `projects/${segments.projects}/locations/${segments.locations}`);
+        const nodes = {};
+        const warnings = [];
+        await Promise.all([...byLocation].map(async ([parent, serviceNodes]) => {
+            let deployed;
+            try {
+                [deployed] = await servicesClient.listServices({ parent });
+            }
+            catch (error) {
+                warnings.push({
+                    message: `Failed to list the Cloud Run services in '${parent}': ${error.message ?? error}`,
+                });
+                return;
+            }
+            const byName = new Map(deployed.map((s) => [s.name, s]));
+            for (const { node, name } of serviceNodes) {
+                const service = byName.get(name);
+                if (!service) {
+                    warnings.push({
+                        message: `The Cloud Run service '${name}' of '${node.id}' does not exist.`,
+                    });
+                    continue;
+                }
+                const deployment = toDeployment(service);
+                const { updatedAt } = deployment;
+                if (updatedAt && updatedAt > environment.at) {
+                    warnings.push({
+                        message: `The Cloud Run service '${name}' of '${node.id}' was updated at ${updatedAt.toISOString()}, after the end of the evaluation window. Its deployment is the current one.`,
+                    });
+                }
+                nodes[node.id] = { data: { deployment } };
+            }
+        }));
+        return { nodes, warnings };
+    },
+};

package/dist/graph/environment/fetchers/cloud-scheduler.d.ts

@@ -0,0 +1,5 @@
+import { type GraphEnvironmentFetcher } from '@causa/workspace-core';
+/**
+ * Reads the last attempt and next run of Cloud Scheduler jobs.
+ */
+export declare const googleCloudScheduler: GraphEnvironmentFetcher;

package/dist/graph/environment/fetchers/cloud-scheduler.js

@@ -0,0 +1,95 @@
+import { ScheduledJobAttemptStatus, } from '@causa/workspace-core';
+import { googleResources } from '../resources.js';
+/**
+ * Returns the data of a scheduled job.
+ * The attempt succeeded if its status code is `OK`. The status message is kept, or the name of the code if the attempt
+ * failed without a message.
+ *
+ * @param job The Cloud Scheduler job.
+ * @param statusCodes The gRPC status codes, which are passed as `google-gax` is imported dynamically.
+ * @returns The data of the node.
+ */
+function toData(job, statusCodes) {
+    const code = job.status?.code ?? statusCodes.OK;
+    const succeeded = code === statusCodes.OK;
+    const message = job.status?.message ||
+        (succeeded ? undefined : (statusCodes[code] ?? `${code}`));
+    return {
+        ...(job.lastAttemptTime
+            ? {
+                lastAttempt: {
+                    time: new Date(job.lastAttemptTime),
+                    status: succeeded
+                        ? ScheduledJobAttemptStatus.Succeeded
+                        : ScheduledJobAttemptStatus.Failed,
+                    ...(message ? { message } : {}),
+                },
+            }
+            : {}),
+        ...(job.scheduleTime && job.state === 'ENABLED'
+            ? { nextRun: new Date(job.scheduleTime) }
+            : {}),
+    };
+}
+/**
+ * Reads the last attempt and next run of Cloud Scheduler jobs.
+ */
+export const googleCloudScheduler = {
+    name: 'googleCloudScheduler',
+    description: 'The `lastAttempt` and `nextRun` of Cloud Scheduler jobs. Paused jobs have no next run. They are the current ones, with a warning when the job was attempted after the end of the evaluation window.',
+    fetch: async (environment) => {
+        const jobs = googleResources(environment, 'cloudscheduler.googleapis.com/Job', 'scheduledJob');
+        const byLocation = Map.groupBy(jobs, ({ segments }) => `projects/${segments.projects}/locations/${segments.locations}`);
+        if (byLocation.size === 0) {
+            return {};
+        }
+        const [{ GoogleApisService }, { Status }] = await Promise.all([
+            import('../../../services/google-apis.js'),
+            import('google-gax'),
+        ]);
+        const client = await environment.context
+            .service(GoogleApisService)
+            .getClient('cloudscheduler', 'v1', {});
+        const nodes = {};
+        const warnings = [];
+        await Promise.all([...byLocation].map(async ([parent, jobNodes]) => {
+            const deployed = new Map();
+            try {
+                let pageToken;
+                do {
+                    const { data } = await client.projects.locations.jobs.list({
+                        parent,
+                        pageSize: 500,
+                        pageToken,
+                    });
+                    (data.jobs ?? []).forEach((j) => j.name && deployed.set(j.name, j));
+                    pageToken = data.nextPageToken ?? undefined;
+                } while (pageToken);
+            }
+            catch (error) {
+                warnings.push({
+                    message: `Failed to list the Cloud Scheduler jobs in '${parent}': ${error.message ?? error}`,
+                });
+                return;
+            }
+            for (const { node, name } of jobNodes) {
+                const job = deployed.get(name);
+                if (!job) {
+                    warnings.push({
+                        message: `The Cloud Scheduler job '${name}' of '${node.id}' does not exist.`,
+                    });
+                    continue;
+                }
+                const data = toData(job, Status);
+                const time = data.lastAttempt?.time;
+                if (time && time > environment.at) {
+                    warnings.push({
+                        message: `The Cloud Scheduler job '${name}' of '${node.id}' was last attempted at ${time.toISOString()}, after the end of the evaluation window. Its last attempt and next run are the current ones.`,
+                    });
+                }
+                nodes[node.id] = { data };
+            }
+        }));
+        return { nodes, warnings };
+    },
+};

package/dist/graph/environment/fetchers/console-links.d.ts

@@ -0,0 +1,14 @@
+import type { GraphEnvironmentFetcher } from '@causa/workspace-core';
+/**
+ * Builds the URL of a page of the Google Cloud console.
+ *
+ * @param segments The segments of the path of the page, which are encoded.
+ * @param project The GCP project.
+ * @param query Additional query parameters.
+ * @returns The URL.
+ */
+export declare function consoleUrl(segments: string[], project: string, query?: Record<string, string>): string;
+/**
+ * Builds links to the Google Cloud console for the nodes' resources.
+ */
+export declare const googleConsoleLinks: GraphEnvironmentFetcher;