Skip to main content

For Google Cloud users

If you are experienced with Google Cloud Platform (GCP), you will find that Crusoe AI Platform shares many foundational concepts. Terms like Project, Revision, Service Account, Topic, and Subscription operate with familiar semantics.

This guide maps GCP concepts to our platform, details key architectural advantages, and provides a direct migration path for your workloads.

Vocabulary Translation​

GCP Service / ConceptCrusoe AI PlatformKey Distinctions
Organization & FoldersOrganizationSingle-tier organizational scope owning projects and user accounts.
ProjectProjectPrimary unit of resource, network, quota, and audit isolation. Everything belongs to a project.
Project ID & Project NumberProject Slug & Short IDReadable slug (ml-team) and permanent short ID (ab12cd) embedded in workload network addresses.
gcloud services enable ...Zero Enablement RequiredEvery platform service is instantly available across all projects without manual API enablement.
IAM Role Binding (roles/run.admin)Project Role: admin or memberStreamlined access model (admin or member) eliminating complex IAM policy authoring.
Google Cloud ConsoleWeb ConsoleWeb management console at https://console.codyhill.dev. See Create an Account.
gcloud CLIplatformctlUnified CLI binary for agents, functions, container services, messaging, and data stores. See Install CLI.
Service Account (sa@project...)Service AccountProject-scoped machine identity (name@<project-short>.cai.local) holding project-level roles.
Service Account Key (JSON)API Key (cai_<keyid>_<secret>)Single-reveal API key generated for service accounts with instant revocation capabilities. See Service Accounts.
Cloud Run ServiceServerless ServiceDirect container-to-HTTPS deployment with automatic scale-to-zero execution.
Cloud Run RevisionRevisionImmutable snapshot of code and configuration created on every deploy, supporting traffic splitting. See Revisions.
Cloud Run Min InstancesMin InstancesKeep baseline capacity warm to eliminate cold starts for low-latency workloads. See Autoscaling.
*.run.app EndpointGateway endpoint, published on demandEvery workload has a canonical address (https://<name>-<project-short>.apps.codyhill.dev), but unlike *.run.app it is reachable only from inside the platform until you publish it: platformctl gateway publish function/<name> --auth none. See Publish an Endpoint.
Cloud Build + Artifact RegistryIntegrated Platform BuildAutomated source-to-container build pipeline managed natively by the platform upon deploy.
Cloud Run FunctionsFunctionEvent-driven serverless code exposing handle(event) across Python, Node.js, Go, and Ruby runtimes.
Entry Point helloWorlddef handle(event) in handler.pyReceives parsed JSON event dicts and returns dictionary responses with optional HTTP status codes.
Vertex AI Agent EngineAgentsServerless execution for ADK, LangGraph, or CrewAI agents with built-in state management.
Agent Development Kit (ADK)Native ADK ExecutionNative execution for unmodified Google ADK agents (agent.py exposing root_agent). See ADK Framework.
Vertex AI SessionsSessionsNative conversation context management replayed automatically to models on each invocation turn.
Vertex AI Memory BankMemoryLong-term memory storage searchable by agents using native search_memory tools.
Gemini Code ExecutionCode SandboxEphemeral, isolated sandbox executing untrusted code securely per invocation.
Vertex AI Vector Search Index & EndpointVectorDB IndexDedicated vector database index queryable instantly upon creation without separate endpoint deployment steps.
Vector Search RestrictsPayload FiltersJSON match and range conditions evaluated natively against vector point payloads. See Search.
ScaNN IndexingHNSW IndexingHigh-performance approximate nearest neighbor (ANN) search using HNSW indexing with native payload filtering.
Memorystore for Redis / ValkeyMemoryStoreManaged in-memory key-value store speaking standard Redis wire protocol.
Cloud Pub/Sub TopicPub/Sub TopicNamed messaging channel supporting fan-out message publishing.
Cloud Pub/Sub SubscriptionSubscriptionDedicated subscriber queue tracking reading positions independently across consumers.
Eventarc / Cloud TasksPub/Sub Topic TriggersDecoupled message processing using Pub/Sub topic subscriptions and function triggers.
Cloud Storage TriggerObjectStore triggerNot an event record. The trigger polls the bucket (poll_seconds, default 60) and POSTs the object's own bytes; the object name is not delivered, and your handler needs no storage client. after_read (move, delete, or none) is required — there is no default.
GCP Workflows / Cloud ComposerPub/Sub Chains / Agent OrchestrationMulti-step workflows orchestrated via Pub/Sub event sequences or AI agent tool chains.
Secret Manager SecretSecretProject-scoped secret management with numbered version history injected directly into workloads.
Cloud LoggingLogsReal-time log streaming with 14-day persistent history surviving container scaling.
Cloud MonitoringLive Metric CountersReal-time visibility into active instances, execution counts, CPU, and memory utilization.
Cloud Audit LogsProject Audit LogAlways-on management operations auditing recorded automatically for all project members.
GCP Quotas & BillingProject QuotasReal-time resource quota tracking providing clear capacity bounds without complex billing sub-SKUs.

Key Similarities​

  • Project Isolation: Projects serve as the core boundary for resources, team membership, quota caps, and security audit logs.
  • Immutable Revisions: Every deployment generates an immutable revision snapshot, enabling seamless traffic allocation and zero-downtime rollbacks.
  • Scale-to-Zero Architecture: Serverless containers, functions, and AI agents scale down to zero when idle and instantly scale up on demand.
  • Service Account Identity Model: Machine identities belong to individual projects, hold role-based permissions, and authenticate using API keys.
  • Native ADK Compatibility: Google ADK agent code runs completely unmodified on the platform.

Architectural Distinctions​

Platform Streamlining​

  • Zero API Enablement Overhead: All platform services are available immediately upon project creation—no gcloud services enable required.
  • Instant VectorDB Readiness: Creating a VectorDB index makes it queryable instantly. You do not need to provision, deploy, or manage separate index endpoints.
  • Integrated Agent State: Agent sessions and long-term memory are built natively into the agent runtime rather than managed as separate sub-products.
  • Consistent Product Model: Single, clear product names across the CLI, web console, and API paths eliminate multi-generational naming confusion.
  • Direct Access Control: Simplified admin and member roles provide clear permission boundaries without configuring granular IAM role bindings.

GCP Migration Considerations​

  • Single-Region High Efficiency: Compute resources operate in high-density, low-latency environments optimized for serverless execution and fast AI inference.
  • Workflow Orchestration: Multi-step workflows utilize Pub/Sub message queues or AI agent tool chains to orchestrate step execution.
  • Secret Lifecycle: A secret update generates a new version but does not touch running workloads — a revision is an immutable snapshot, so the running one keeps its old environment. Run platformctl secrets bindings apply <workload> (or POST /v1/projects/{id}/agents/{agent}/secret-maps:apply) to write the current version onto the workload and roll a new revision.

Hands-On: Deploy a Function Like a Cloud Run Function​

If you have written GCP HTTP functions, the handler signature will be immediately familiar. With platformctl installed and authenticated:

mkdir hello-http
cat > hello-http/handler.py <<'EOF'
def handle(event):
    who = event.get("name") or event.get("message") or "world"
    return {"greeting": f"Hello, {who}!"}
EOF
platformctl functions deploy ./hello-http --name hello-http

Deployment output — one line per state transition, and a last line that does not pretend the address is answering yet:

packaging ./hello-http...
uploading hello-http (0.3 KiB, framework=function, runtime=python)...
build 7c41d9e2 accepted
state: building -> deploying
state: deploying -> ready
hello-http is ready (private). Publish it to serve on https://hello-http-ab12cd.apps.codyhill.dev

Unlike a Cloud Run service deployed with --allow-unauthenticated, the function is private until you publish it — reachable from inside the platform, never from the internet.

platformctl invoke reaches it either way, but it prints the output key an agent returns, and a function's return value has no output key — so the first line comes back empty:

platformctl invoke hello-http "ping"

(session: 3f6c1f0e-9c1c-4f1a-8f2e-2a0d5f6b7c81)

To see what the handler returned, publish the function and call its address:

platformctl gateway publish function/hello-http --auth none
export FUNC_URL=https://hello-http-ab12cd.apps.codyhill.dev
curl -s "$FUNC_URL" -H 'content-type: application/json' -d '{"name":"ping"}'
{"greeting": "Hello, ping!"}

No API switches to flip and no Artifact Registry repositories to pre-configure; publishing is the one step Cloud Run folds into the deploy. See the full Function Quickstart.

Workload Migration Guide​

GCP WorkloadCrusoe AI Platform Destination
Cloud Run ServiceServerless Overview and Autoscaling
Cloud Run FunctionFunction Quickstart and Runtimes
Vertex AI Agent Engine DeploymentAgent Quickstart and ADK Framework
ADK ToolsTools — native Python tool functions, run in a one-use sandbox with an empty environment (no model key, no bound secrets, no platform URLs) and with internal networks blocked. A tool that needs a credential or an internal service belongs in an MCP server.
Vertex AI Vector Search IndexVectorDB Quickstart and Search
Memorystore for RedisMemoryStore Quickstart
Cloud Pub/Sub Topics & SubscriptionsPub/Sub Quickstart and Publish & Consume
GCP Workflows / Cloud ComposerPub/Sub Event Chains or Agent Tool Pipelines
Secret Manager SecretsManage Secrets and Use Secrets in Workloads
IAM Roles, Service Accounts & KeysProjects & Access and CI/CD Service Accounts

Next Steps​