Create bucket in specific location (and region)

[akashkrishnan]

I did a quick search in the issues (and documentation) and did not find a way to create buckets in specific locations and regions. Does the API support this?

[stephenplusplus]

Yes, although we should add an example in our docs, since it's not very clear. Your call to createBucket lets you provide an object that we pass up to what the API here expects (under "Request body").

storage.createBucket('your-new-bucket', {
  location: 'ASIA-EAST1',
  storageClass: 'DURABLE_REDUCED_AVAILABILITY'
}, function(err, bucket, apiResponse) {
  // bucket.metadata.location = 'ASIA-EAST1
});

[jgeewax]

1. Is this documented anywhere ? Seems like a common request...
2. Is the location case sensitive?
3. Should we make those constants variables to avoid typos?
4. Ditto for storage class...?

[stephenplusplus]

Is the location case sensitive?

It is. This is the format the upstream API expects. We leave this window open so we don't have to design custom support for every use case.

---

Should we make those constants variables to avoid typos?
Ditto for storage class...?

The more we localize, the more likely we are to go stale as the upstream moves forward or makes changes. To know what we've made constants, the user would have to hit our docs. I'd rather pass them onto the official JSON API docs and let them do the explaining: https://cloud.google.com/storage/docs/json_api/v1/buckets/insert

As an example of doc modularity, the insert docs themselves for the location property deflect to another thorough doc site:

location string The location of the bucket. Object data for objects in the bucket resides in physical storage within this region. Defaults to US. See the developer's guide for the authoritative list.

---

Is this documented anywhere ?

Not currently, but I intend to. In that example, it will link out to the places I linked above to complete the story.

---

Seems like a common request...

While I went off on all my reasons not to localize and blah blah, we do want to make exceptions for really common cases. If you think this is one of them, can you think of a way we can make it easier than docs & links? Maybe a way other libraries have done it? I'm specifically afraid of making constants out of locations that may change. Also, storage.locations.ASIAEAST1 doesn't seem easier to remember or more developer friendly than just accepting a string 'ASIA-EAST1`.

---

@akashkrishnan feel free to chime in with any thoughts on the way you would prefer creating a bucket in a location to look like :)

[jgeewax]

I'd rather pass them onto the official JSON API docs

That's a fair point, but it means also that instead of getting a "variable not found" you get a "bad request". I'd be fine with this so long as the error message the user gets is helpful and says more than "bad request" (maybe "the zone provided (us-aisa-1a) wasn't valid")

If it doesn't today, we should create an issue for that.

Not currently, but I intend to.

Cool.

[stephenplusplus]

so long as the error message the user gets is helpful and says more than "bad request" (maybe "the zone provided (us-aisa-1a) wasn't valid")

:( Not helpful:

https://cloud.google.com/storage/docs/regional-buckets has a list of regional locations:

• ASIA-EAST1 - Eastern Asia-Pacific
• US-CENTRAL1 - Central United States
• US-CENTRAL2 - Central United States
• US-EAST1 - Eastern United States
• US-EAST2 - Eastern United States
• US-EAST3 - Eastern United States
• US-WEST1 - Western United States

Should we check the provided location against this list? I'm more in favor of

1. wishing that responsibility on the upstream API
2. trusting users know which value is likely to be wrong. If confused, they can get more clarity from our yet to be elaborted docs that link to the list of locations above

[akashkrishnan]

@stephenplusplus Yes, your response and update to the documentation make sense, and it is exactly what I was expecting---just needed it written out in the documentation for clarity.

As for the location and region constants, I would also lean towards points 1 and 2, just because it would make it easier to maintain this API.