|
| 1 | +# Cloud Connect on a Development Machine |
| 2 | + |
| 3 | +Works with `v2.2+` |
| 4 | + |
| 5 | +Connect this directory to Spice Cloud with one command, watch a deployment apply to the running instance without a restart, stop it, and reconnect. |
| 6 | + |
| 7 | +The recipe is deliberately minimal: one public dataset, no infrastructure, no credentials on disk. What it demonstrates is the [Cloud Connect](https://spiceai.org/docs/deployment/cloud-connect) lifecycle on the machine you develop on. |
| 8 | + |
| 9 | +You will: |
| 10 | + |
| 11 | +1. Connect this directory and get a running instance attached to a new Spice Cloud project. |
| 12 | +2. Deploy a change that applies live, with no restart and no serving gap. |
| 13 | +3. Deploy a change that needs a restart, and see exactly which settings are pending. |
| 14 | +4. Stop with `Ctrl-C` and reconnect with `spice run` — the identity survives. |
| 15 | +5. Release the instance and delete its project. |
| 16 | + |
| 17 | +## Prerequisites |
| 18 | + |
| 19 | +- The Spice CLI, `v2.2.0` or later: |
| 20 | + |
| 21 | + ```bash |
| 22 | + curl https://install.spiceai.org | /bin/bash |
| 23 | + ``` |
| 24 | + |
| 25 | +- A Spice Cloud account with the **owner** or **admin** role in at least one organization. Those roles may enroll an instance and create a project; `member` may not. |
| 26 | +- Outbound HTTPS to `api.spice.ai` and to the Cloud Connect gateway. |
| 27 | + |
| 28 | +No `spice login` beforehand — `spice connect` runs login inline if needed. |
| 29 | + |
| 30 | +**Cost:** a Spice Cloud project on the free tier. Step 6 deletes it. |
| 31 | + |
| 32 | +## 1. Connect |
| 33 | + |
| 34 | +Clone the cookbook and enter this recipe. The directory name is the project-name default, so run from `cloud-connect-dev` exactly: |
| 35 | + |
| 36 | +```bash |
| 37 | +git clone https://github.com/spiceai/cookbook.git |
| 38 | +cd cookbook/cloud-connect-dev |
| 39 | +spice connect |
| 40 | +``` |
| 41 | + |
| 42 | +With no saved login, `spice connect` offers two choices rather than failing: |
| 43 | + |
| 44 | +```console |
| 45 | +? Connect this directory to Spice Cloud › |
| 46 | +❯ Log in to Spice Cloud (recommended) |
| 47 | + Use an enrollment key |
| 48 | +``` |
| 49 | + |
| 50 | +Choose **Log in to Spice Cloud**. Login runs in the same process and the connect flow continues — there is no second command. |
| 51 | + |
| 52 | +Next the organization. If your login is owner or admin in exactly one, it is named and used: |
| 53 | + |
| 54 | +```console |
| 55 | +Organization: <org> (owner) |
| 56 | +``` |
| 57 | + |
| 58 | +If several are eligible, pick one. Then the project name, defaulted from this directory: |
| 59 | + |
| 60 | +```console |
| 61 | +? Project name › cloud-connect-dev |
| 62 | +``` |
| 63 | + |
| 64 | +Press Enter to accept it. If the name is already taken in that organization, the CLI explains and re-prompts with an editable `cloud-connect-dev-2`; accept whatever it offers and use that name for the rest of the recipe. |
| 65 | + |
| 66 | +The runtime then starts in your terminal: |
| 67 | + |
| 68 | +```console |
| 69 | +Starting the Spice runtime. Press Ctrl-C to stop it. |
| 70 | +... |
| 71 | +INFO Spice Cloud Connect: connected to <org> / cloud-connect-dev |
| 72 | +INFO Monitor: https://spice.ai/<org>/cloud-connect-dev/monitor |
| 73 | +``` |
| 74 | + |
| 75 | +Leave it running. Open the monitor link — the instance appears online, with the `data` dataset from `spicepod.yaml`. |
| 76 | + |
| 77 | +Confirm from a second terminal, in the same directory: |
| 78 | + |
| 79 | +```bash |
| 80 | +cd cookbook/cloud-connect-dev |
| 81 | +spice connect status |
| 82 | +``` |
| 83 | + |
| 84 | +```console |
| 85 | +Spice Cloud Connect: connected — <org> / cloud-connect-dev |
| 86 | + instance: inst_<id> |
| 87 | + identity: <path>/cloud-connect-dev/.spice/identity.json |
| 88 | + gateway: connect.aws.spiceai.io:443 |
| 89 | + expiry: unix=<seconds> (expired=false) |
| 90 | + service: not_installed |
| 91 | + starts: not started automatically |
| 92 | + logs: not configured by this service definition |
| 93 | + deployment: none yet — this instance runs its local spicepod until an app is deployed |
| 94 | + secrets: none delivered yet — deploy the app to deliver them |
| 95 | + monitor: https://spice.ai/<org>/cloud-connect-dev/monitor |
| 96 | +No service is installed for this directory. Run `spice connect service install` to keep this instance running across reboots. |
| 97 | +``` |
| 98 | + |
| 99 | +Note the PID of the running runtime — nothing below changes it: |
| 100 | + |
| 101 | +```bash |
| 102 | +pgrep -f 'spiced' | head -1 |
| 103 | +``` |
| 104 | + |
| 105 | +## 2. Deploy a change that applies live |
| 106 | + |
| 107 | +In the portal, edit the project's Spicepod and add a view, then deploy. Anything under `datasets`, `views`, `models`, `functions`, or an added `catalog` is reconciled into the running process: |
| 108 | + |
| 109 | +```yaml |
| 110 | +views: |
| 111 | + - name: recent |
| 112 | + sql: SELECT * FROM data LIMIT 10 |
| 113 | +``` |
| 114 | +
|
| 115 | +The foreground terminal reports the deployment. There is no restart and no gap in serving: |
| 116 | +
|
| 117 | +```console |
| 118 | +INFO Spice Cloud Connect: applied the deployed spicepod (1 datasets, 0 models, 0 catalogs, 1 views) |
| 119 | +``` |
| 120 | +
|
| 121 | +Check the PID again — it is unchanged — and query the new view while the same process serves it: |
| 122 | +
|
| 123 | +```bash |
| 124 | +spice sql |
| 125 | +``` |
| 126 | + |
| 127 | +```sql |
| 128 | +SELECT count(*) FROM recent; |
| 129 | +``` |
| 130 | + |
| 131 | +`spice connect status` now names the deployed Spicepod and reports no pending restart: |
| 132 | + |
| 133 | +```console |
| 134 | + deployment: <path>/cloud-connect-dev/.spice/spicepod-cloud-managed.yml |
| 135 | + secrets: none (the last deployment delivered no secrets) |
| 136 | +``` |
| 137 | + |
| 138 | +## 3. Deploy a change that needs a restart |
| 139 | + |
| 140 | +Some sections are read only when the runtime starts. Add one in the portal — for example a `runtime` setting — and deploy again: |
| 141 | + |
| 142 | +```yaml |
| 143 | +runtime: |
| 144 | + task_history: |
| 145 | + captured_output: truncated |
| 146 | +``` |
| 147 | +
|
| 148 | +The instance keeps serving its current configuration. The deployment is persisted as desired state and the affected sections are named: |
| 149 | +
|
| 150 | +```console |
| 151 | +INFO Spice Cloud Connect: applied the deployed spicepod (1 datasets, 0 models, 0 catalogs, 1 views); runtime takes effect when this instance next starts |
| 152 | +``` |
| 153 | +
|
| 154 | +The pending list is sticky and readable from three places, all backed by the same state: |
| 155 | +
|
| 156 | +```bash |
| 157 | +spice connect status |
| 158 | +``` |
| 159 | + |
| 160 | +```console |
| 161 | + restart: required for runtime |
| 162 | +``` |
| 163 | + |
| 164 | +```bash |
| 165 | +spice connect status --output json | jq .deployment.restart_required |
| 166 | +``` |
| 167 | + |
| 168 | +```console |
| 169 | +[ |
| 170 | + "runtime" |
| 171 | +] |
| 172 | +``` |
| 173 | + |
| 174 | +```bash |
| 175 | +curl -s http://127.0.0.1:8090/v1/cloud-connect/status | jq |
| 176 | +``` |
| 177 | + |
| 178 | +```console |
| 179 | +{ |
| 180 | + "instance_id": "inst_<id>", |
| 181 | + "restart_required": [ |
| 182 | + "runtime" |
| 183 | + ] |
| 184 | +} |
| 185 | +``` |
| 186 | + |
| 187 | +The PID is still unchanged, and queries still work. In the foreground there is no supervisor to restart the instance — that is step 4. |
| 188 | + |
| 189 | +## 4. Stop and reconnect |
| 190 | + |
| 191 | +In the foreground terminal, press `Ctrl-C`. The runtime stops. The Cloud identity is **not** released: the instance shows as offline in the portal and `.spice/identity.json` is still on disk. |
| 192 | + |
| 193 | +```bash |
| 194 | +spice connect status |
| 195 | +``` |
| 196 | + |
| 197 | +```console |
| 198 | +Spice Cloud Connect: connected — <org> / cloud-connect-dev |
| 199 | +``` |
| 200 | + |
| 201 | +Start it again from the same directory. No Cloud Connect flag is needed — the identity reconnects it: |
| 202 | + |
| 203 | +```bash |
| 204 | +spice run |
| 205 | +``` |
| 206 | + |
| 207 | +```console |
| 208 | +INFO Spice Cloud Connect: connected to <org> / cloud-connect-dev |
| 209 | +INFO Monitor: https://spice.ai/<org>/cloud-connect-dev/monitor |
| 210 | +``` |
| 211 | + |
| 212 | +This start activates the desired configuration, so the pending list clears: |
| 213 | + |
| 214 | +```bash |
| 215 | +spice connect status |
| 216 | +``` |
| 217 | + |
| 218 | +The `restart:` line is gone. |
| 219 | + |
| 220 | +`spice connect` from this directory does the same thing. It never enrolls a second instance — an existing identity always wins. |
| 221 | + |
| 222 | +## 5. Validate locally |
| 223 | + |
| 224 | +`validate.sh` checks the parts of this recipe that need no Spice Cloud account and no credentials. Run it any time: |
| 225 | + |
| 226 | +```bash |
| 227 | +./validate.sh |
| 228 | +``` |
| 229 | + |
| 230 | +It asserts that the CLI is new enough, that the project-name default derives from this directory with no random fallback, that `spice connect status` reports a coherent snapshot in both output formats, that a non-interactive `spice connect` refuses instead of hanging, and that no credential or generated identity is staged for commit. |
| 231 | + |
| 232 | +## 6. Clean up |
| 233 | + |
| 234 | +Stop the runtime first — removal refuses while `spiced` is running — then release the instance: |
| 235 | + |
| 236 | +```bash |
| 237 | +spice connect remove |
| 238 | +``` |
| 239 | + |
| 240 | +```console |
| 241 | +This will delete this instance's project in Spice Cloud and remove the instance from this host: |
| 242 | + directory: <path>/cloud-connect-dev |
| 243 | + identity: <path>/cloud-connect-dev/.spice/identity.json (deleted) |
| 244 | +? Continue? › yes |
| 245 | +Deleted project cloud-connect-dev in Spice Cloud. |
| 246 | +Spice Cloud Connect identity cleared. To re-enroll this directory, mint a new enrollment key in the Spice Cloud portal and start the runtime with `spiced --token <enrollment-key>`. |
| 247 | +``` |
| 248 | + |
| 249 | +The project is deleted with your logged-in user session, so stay logged in to the same organization. Confirm the directory is clear: |
| 250 | + |
| 251 | +```bash |
| 252 | +spice connect status |
| 253 | +``` |
| 254 | + |
| 255 | +```console |
| 256 | +Spice Cloud Connect: not connected (<path>/cloud-connect-dev) |
| 257 | +``` |
| 258 | + |
| 259 | +## Notes |
| 260 | + |
| 261 | +- **Nothing is committed.** `.spice/` is gitignored: the issued identity, the cloud-managed Spicepod, and the delivered-secrets cache all live there. `validate.sh` checks it. |
| 262 | +- **`spice connect` needs a terminal.** It is interactive; on a non-interactive stdin it exits and points at `spiced --token <enrollment-key>` for [headless enrollment](https://spiceai.org/docs/deployment/cloud-connect/headless). |
| 263 | +- **Cancelling is safe.** `Esc` or `Ctrl-C` at any prompt is a clean exit. An interrupted enrollment resumes on the next run rather than creating a duplicate instance or project. |
| 264 | +- **This recipe is foreground only.** To keep the instance running across reboots on Linux, see [Cloud Connect as a persistent service](https://spiceai.org/docs/deployment/cloud-connect/service). The managed service lifecycle does not yet support macOS or Windows; there, the foreground flow in this recipe is the development story. |
| 265 | + |
| 266 | +## Learn more |
| 267 | + |
| 268 | +- [Cloud Connect](https://spiceai.org/docs/deployment/cloud-connect) |
| 269 | +- [`spice connect` reference](https://spiceai.org/docs/cli/reference/connect) |
0 commit comments