|
| 1 | +--- |
| 2 | +name: Add Pod to Elastic Search |
| 3 | +about: Checklist for onboarding a new ProudCity site (pod) to the Elasticsearch cluster |
| 4 | +title: 'ADD TO ELASTIC: <site-slug>' |
| 5 | +labels: elastic, onboarding |
| 6 | +assignees: curtismchale |
| 7 | + |
| 8 | +--- |
| 9 | + |
| 10 | +Use this every time we add a new pod/site that needs ElasticPress search. Skipping the cluster allowlist step will silently break sync once the new index name is rejected by `action.auto_create_index`. |
| 11 | + |
| 12 | +See full walkthrough: `~/Documents/developers/ProudCity Developers/How To/How to Add a New Pod to Elastic Search.md`. |
| 13 | + |
| 14 | +## Site info |
| 15 | + |
| 16 | +- Site slug (becomes the ES index name): `<lowercase-slug>` |
| 17 | +- Pod namespace: `prod` / `test` / other |
| 18 | +- Search cohort? (does this site appear in another site's "search all" cohort): yes / no |
| 19 | + |
| 20 | +## Pre-flight |
| 21 | + |
| 22 | +- [ ] Slug is lowercase, starts with `[a-z0-9]`, only contains `[a-z0-9_-]`, ≤ 64 chars (matches the validation regex in `wp-proud-search-elastic`) |
| 23 | +- [ ] Confirm the slug is not already in use as an ES index: `kubectl exec -n elasticsearch elasticsearch-master-0 -- curl -s 'localhost:9200/_cat/indices?v' | grep <slug>` |
| 24 | + |
| 25 | +## Update the cluster `auto_create_index` allowlist |
| 26 | + |
| 27 | +If the new slug doesn't already match an existing prefix-wildcard entry in the allowlist, add it. |
| 28 | + |
| 29 | +- [ ] Read current setting: |
| 30 | + ``` |
| 31 | + kubectl exec -n elasticsearch elasticsearch-master-0 -- \ |
| 32 | + curl -s 'localhost:9200/_cluster/settings?pretty' | grep auto_create_index |
| 33 | + ``` |
| 34 | +- [ ] PUT updated setting (append `,<slug>*` to the existing comma-separated list, keeping `.*` as the last entry for system indices): |
| 35 | + ``` |
| 36 | + kubectl exec -n elasticsearch elasticsearch-master-0 -- curl -s -X PUT \ |
| 37 | + 'localhost:9200/_cluster/settings' \ |
| 38 | + -H 'Content-Type: application/json' \ |
| 39 | + -d '{"persistent":{"action.auto_create_index":"<full updated allowlist>"}}' |
| 40 | + ``` |
| 41 | +- [ ] Verify the response contains `"acknowledged":true` and the new entry is present. |
| 42 | + |
| 43 | +## Update the cohort option (only if this site participates in cross-site search) |
| 44 | + |
| 45 | +The `proud-elastic-search-cohort` WP option controls which slugs are valid `filter_index` values in the search form. The plugin allowlist enforces this. If the new site should appear in a parent site's "search all", add it there. |
| 46 | + |
| 47 | +- [ ] On the parent site that owns the cohort, update `proud-elastic-search-cohort` to include the new slug. |
| 48 | +- [ ] Verify by inspecting the option: `wp --allow-root option get proud-elastic-search-cohort --format=json`. |
| 49 | + |
| 50 | +## Run the initial ElasticPress sync |
| 51 | + |
| 52 | +- [ ] SSH into the new pod: `pc kube ssh <namespace> <pod-name>` |
| 53 | +- [ ] Run the full sync sequence: |
| 54 | + ``` |
| 55 | + wp --allow-root elasticpress stop-sync && \ |
| 56 | + wp --allow-root elasticpress clear-sync && \ |
| 57 | + wp --allow-root elasticpress put-mapping && \ |
| 58 | + wp --allow-root elasticpress sync --force --show-errors |
| 59 | + ``` |
| 60 | +- [ ] Confirm the new index appears with docs: |
| 61 | + ``` |
| 62 | + kubectl exec -n elasticsearch elasticsearch-master-0 -- \ |
| 63 | + curl -s 'localhost:9200/_cat/indices?v' | grep <slug> |
| 64 | + ``` |
| 65 | + |
| 66 | +## Verification |
| 67 | + |
| 68 | +- [ ] ES cluster status still green: `kubectl exec -n elasticsearch elasticsearch-master-0 -- curl -s localhost:9200/_cluster/health?pretty` |
| 69 | +- [ ] Search on the new site returns expected results. |
| 70 | +- [ ] If site joined a cohort, search on the parent site with `filter_index` set to the new slug returns results scoped to the new site only. |
| 71 | + |
| 72 | +## Rollback |
| 73 | + |
| 74 | +If something is wrong, restoring the previous allowlist is a single PUT with the old value. Removing a probationary index is `DELETE /<slug>`. The cohort option is just a WP option update. |
| 75 | + |
| 76 | +## References |
| 77 | + |
| 78 | +- Cluster allowlist motivation: pc-dev-issues#266 (Copy Fail-era ES path-injection fix) |
| 79 | +- Plugin validation: `wp-proud-search-elastic/lib/elasticsearch.class.php` `query_alter` and `ep_search_request_path` |
| 80 | +- Reindex troubleshooting: `~/Documents/developers/ProudCity Developers/How To/How to Fix Elastic Search Index Failures.md` |
0 commit comments