5 ms·

I find the GCP documentation to be lacking compared to AWS. Specifically while using GCP with Terraform I hit more frustrating nonsense error messages with litt

I find the GCP documentation to be lacking compared to AWS. Specifically while using GCP with Terraform I hit more frustrating nonsense error messages with little to no google hits or undocumented behavior around IAM config compared to my experience doing similar things on AWS.

shell0x 3y ago
100%. My experience has been the same. The docs have their shortcomings and I ended up reading through so many Github issues and random blog posts trying to resolve the issues. From a documentation perspective, AWS is still the best.
- s-xyz 3y ago
  Wow I would literally say the opposite. I even use GCP docs as an example for my engineers on how to write proper docs, and did several workshops using the GCP docs as reference. Happy to share the presentation if interested.
  - Something1234 3y ago
    Would be interested in the presentation if you can share publicly
div_zero 3y ago
I'm a technical writing manager on GCP, and we are actively working on improving Terraform documentation. Thank you for bringing up two significant problems with using TF on GCP. If you are willing (and of course have the time), we would love to hear other issues you - or anyone else who reads this thread - are having with TF documentation on GCP as we try and make things better.
- mdaniel 3y ago
  Given: https://registry.terraform.io/providers/hashicorp/google/5.3.0/docs/resources/cloud_run_v2_service https://registry.terraform.io/providers/hashicorp/google/5.3... how would any reasonable person know what https://registry.terraform.io/providers/hashicorp/google/5.3.0/docs/resources/google_project_service https://registry.terraform.io/providers/hashicorp/google/5.3... to enable without (a) trying it and squinting at the error message (b) clicking on the API documentation <https://cloud.google.com/run/docs/reference/rest/v2/projects.locations.services https://cloud.google.com/run/docs/reference/rest/v2/projects...> then realizing it, also, does not mention run.googleapis.com, click on "supported service endpoints" <https://cloud.google.com/run/docs/reference/rest#rest_endpoints https://cloud.google.com/run/docs/reference/rest#rest_endpoi...> and only then learning about https://cloud.google.com/run/docs/reference/rest#service:-run.googleapis.com https://cloud.google.com/run/docs/reference/rest#service:-ru... Repeat for https://registry.terraform.io/providers/hashicorp/google/5.3.0/docs/resources/cloud_identity_group https://registry.terraform.io/providers/hashicorp/google/5.3... although in both cases I guess the astute reader may have spotted the run.googleapis.com in the forbidden service labels and cloudidentity.googleapis.com in the example Since, to the best of my knowledge those bindings are auto generated <https://github.com/GoogleCloudPlatform/magic-modules#magic-modules https://github.com/GoogleCloudPlatform/magic-modules#magic-m...>, I would hypothesize it is not insurmountable drop in the seemingly existing declaration of APIs required: https://github.com/GoogleCloudPlatform/magic-modules/blob/7d76e3b6f834bcea8f0edf086207af30da5e4665/mmv1/products/cloudrunv2/product.yaml#L26-L29 https://github.com/GoogleCloudPlatform/magic-modules/blob/7d... https://github.com/GoogleCloudPlatform/magic-modules/blob/7d76e3b6f834bcea8f0edf086207af30da5e4665/mmv1/products/cloudidentity/product.yaml#L26-L29 https://github.com/GoogleCloudPlatform/magic-modules/blob/7d...
- robmsmt 3y ago
  I am about to go through this so happy to give feedback
- nknealk 3y ago
  Can you please update the terraform docs for google batch? In [1] it’s really difficult to know what everything in the json configuration is under the base64encode() call. What levers can I pull? How do I run something more complex than hello world? Do I need my CICD to upload scripts to GCS and have the instance download them at runtime and hardcode that path into the batch script? [1] https://cloud.google.com/batch/docs/create-run-job-using-terraform-and-cloud-scheduler https://cloud.google.com/batch/docs/create-run-job-using-ter...
  - sojacobs7 3y ago
    It seems as though Google Batch does not have a native Terraform resource. The document in [1] seems like a workaround that leverages the Cloud Scheduler Terraform resource, but submit a job using the JSON configuration. The various fields that can be used in the JSON are within [2]. Regarding using GCS there is an example in [3]. I found more samples in [4] [2] https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs https://cloud.google.com/batch/docs/reference/rest/v1/projec... [3] https://cloud.google.com/batch/docs/create-run-job-storage#use-bucket https://cloud.google.com/batch/docs/create-run-job-storage#u... [4] https://github.com/GoogleCloudPlatform/batch-samples/tree/main/api-samples https://github.com/GoogleCloudPlatform/batch-samples/tree/ma...
- clutchdude 3y ago
  This is probably more a request at the compute team/gke teams but...spot management. For example, managing a spot fleet in AWS via terraform is filled with features and levers I can pull. It's easy to manage basic scale-out/scale-in procedures and allows me to set thresholds. In GCP, as I understand it, I can only manage a node pool at a basic level. EDIT: Also, yell at the people who manage the python library. https://cloud.google.com/python/docs/reference/container/latest https://cloud.google.com/python/docs/reference/container/lat... Generated samples suck - take a look at the boto3 docs and see if they tell you to go look at code generated samples.
- rendaw 3y ago
  Rinse and repeat - someone complains about cloud provider, a cloud provider person shows up and makes a "we want to hear more about your problems" statement, people reply, they do nothing. How many times has this happened? I'm more disgusted by the farce than by the lack of action. Don't you have feedback buttons on the docs? What happens to the feedback from those? Please prove you consider feedback before asking people for more of it.
  - perlwle 3y ago
    A few months ago I was working on migrating cloud build for a personal project and hit a documentation error. Submitted a correction via the feedback button and it got fixed few days later. To be honest I was a little surprised by how fast it got fixed.
- dantiberian 3y ago
  A general issue I have with GCP docs is that they are overly implicit. Often the interaction of two features is implied but not specified. Another issue I have is when implementation details are waved away rather than explained. It adds up to an experience where I am trying to read between the lines of the GCP docs for a feature to understand what is really happening. AWS docs are the opposite. They are often very long and verbose, but once you read the whole manual, you can be guaranteed to have a good understanding of the service. My advice for the Google team would be that if you are ever writing documentation and ask yourself “does the customer really need to know about this?”, the answer should always be yes.
aaarrm 3y ago
I've not used AWS but have been continuously curious if their docs are as scattered as GCP's, this is good to finally know.
adrr 3y ago
Google's support is the worst. Have an issue like those random nonsense error messages, good luck getting it resolved. AWS is complete the opposite. I had an issue Aurora Postgres and got to chat with the product manager of the product. Google could have the best products on the market but no one is going to use them if the support isn't there. I was sad when Looker got bought by google. I remember having issues with setting up looker and using their chat functionality and having the CEO of Looker answer my question.
- latchkey 3y ago
  > Google's support is the worst. 5 minutes later, the "technical writing manager on GCP", makes a helpful comment on this thread.
  - mdaniel 3y ago
    Well, AIUI "reach the front page of HN" was always the only cited way of getting any help with a Google problem, so in that way this is a derivative of that scenario
    - mdhb 3y ago
      Also I never see this mentioned but just for anyone who isn’t clear… Google do actually offer great support, I pay like $30 a month for it and I can speak with real engineers who give super detailed answers. It’s just not free. But the paid offering is great in my experience.
      - _cenw 3y ago
        I've used GCP support on accounts with huge support contracts and enterprise agreements and it's still a bit of a wash if you get good support on your first, second or even third run around the reply button. At least it isn't (paid) Azure Support - that one is noticeably outsourced to people that sometimes lack basic comprehension for the problem. I once asked about their VPN Gateway and got a random API Gateway response, then nothing for a week, and then a new rep.
gorjusborg 3y ago
I had the same gripe when I worked with GCP. Their stuff is exotic, and had weird behaviors in corners, but the docs didn't give you enough context to steer away from them. However, over the last 5 years or so, AWS docs have gotten worse. So I guess now that they are both bad I can't complain?
- denvrede 3y ago
  Did they? Do you have an example at hand? We ran into "weird" issues a lot of times with AWS services just to discover afterwards that almost all of them were covered by their documentation. It was totally our fault and these were also no "hidden" docs.
slotrans 3y ago
Every GCP product is poorly documented. There are often no examples at all, and when there are they only cover the "hello world" case. Last I tried, the documented examples for Cloud Functions v2 simply did not work.

shell0x 3y ago

100%. My experience has been the same. The docs have their shortcomings and I ended up reading through so many Github issues and random blog posts trying to resolve the issues. From a documentation perspective, AWS is still the best.

s-xyz 3y ago
Wow I would literally say the opposite. I even use GCP docs as an example for my engineers on how to write proper docs, and did several workshops using the GCP docs as reference. Happy to share the presentation if interested.
- Something1234 3y ago
  Would be interested in the presentation if you can share publicly

div_zero 3y ago

I'm a technical writing manager on GCP, and we are actively working on improving Terraform documentation. Thank you for bringing up two significant problems with using TF on GCP. If you are willing (and of course have the time), we would love to hear other issues you - or anyone else who reads this thread - are having with TF documentation on GCP as we try and make things better.

mdaniel 3y ago
Given: https://registry.terraform.io/providers/hashicorp/google/5.3.0/docs/resources/cloud_run_v2_service https://registry.terraform.io/providers/hashicorp/google/5.3... how would any reasonable person know what https://registry.terraform.io/providers/hashicorp/google/5.3.0/docs/resources/google_project_service https://registry.terraform.io/providers/hashicorp/google/5.3... to enable without (a) trying it and squinting at the error message (b) clicking on the API documentation <https://cloud.google.com/run/docs/reference/rest/v2/projects.locations.services https://cloud.google.com/run/docs/reference/rest/v2/projects...> then realizing it, also, does not mention run.googleapis.com, click on "supported service endpoints" <https://cloud.google.com/run/docs/reference/rest#rest_endpoints https://cloud.google.com/run/docs/reference/rest#rest_endpoi...> and only then learning about https://cloud.google.com/run/docs/reference/rest#service:-run.googleapis.com https://cloud.google.com/run/docs/reference/rest#service:-ru... Repeat for https://registry.terraform.io/providers/hashicorp/google/5.3.0/docs/resources/cloud_identity_group https://registry.terraform.io/providers/hashicorp/google/5.3... although in both cases I guess the astute reader may have spotted the run.googleapis.com in the forbidden service labels and cloudidentity.googleapis.com in the example Since, to the best of my knowledge those bindings are auto generated <https://github.com/GoogleCloudPlatform/magic-modules#magic-modules https://github.com/GoogleCloudPlatform/magic-modules#magic-m...>, I would hypothesize it is not insurmountable drop in the seemingly existing declaration of APIs required: https://github.com/GoogleCloudPlatform/magic-modules/blob/7d76e3b6f834bcea8f0edf086207af30da5e4665/mmv1/products/cloudrunv2/product.yaml#L26-L29 https://github.com/GoogleCloudPlatform/magic-modules/blob/7d... https://github.com/GoogleCloudPlatform/magic-modules/blob/7d76e3b6f834bcea8f0edf086207af30da5e4665/mmv1/products/cloudidentity/product.yaml#L26-L29 https://github.com/GoogleCloudPlatform/magic-modules/blob/7d...
robmsmt 3y ago
I am about to go through this so happy to give feedback
nknealk 3y ago
Can you please update the terraform docs for google batch? In [1] it’s really difficult to know what everything in the json configuration is under the base64encode() call. What levers can I pull? How do I run something more complex than hello world? Do I need my CICD to upload scripts to GCS and have the instance download them at runtime and hardcode that path into the batch script? [1] https://cloud.google.com/batch/docs/create-run-job-using-terraform-and-cloud-scheduler https://cloud.google.com/batch/docs/create-run-job-using-ter...
- sojacobs7 3y ago
  It seems as though Google Batch does not have a native Terraform resource. The document in [1] seems like a workaround that leverages the Cloud Scheduler Terraform resource, but submit a job using the JSON configuration. The various fields that can be used in the JSON are within [2]. Regarding using GCS there is an example in [3]. I found more samples in [4] [2] https://cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs https://cloud.google.com/batch/docs/reference/rest/v1/projec... [3] https://cloud.google.com/batch/docs/create-run-job-storage#use-bucket https://cloud.google.com/batch/docs/create-run-job-storage#u... [4] https://github.com/GoogleCloudPlatform/batch-samples/tree/main/api-samples https://github.com/GoogleCloudPlatform/batch-samples/tree/ma...
clutchdude 3y ago
This is probably more a request at the compute team/gke teams but...spot management. For example, managing a spot fleet in AWS via terraform is filled with features and levers I can pull. It's easy to manage basic scale-out/scale-in procedures and allows me to set thresholds. In GCP, as I understand it, I can only manage a node pool at a basic level. EDIT: Also, yell at the people who manage the python library. https://cloud.google.com/python/docs/reference/container/latest https://cloud.google.com/python/docs/reference/container/lat... Generated samples suck - take a look at the boto3 docs and see if they tell you to go look at code generated samples.
rendaw 3y ago
Rinse and repeat - someone complains about cloud provider, a cloud provider person shows up and makes a "we want to hear more about your problems" statement, people reply, they do nothing. How many times has this happened? I'm more disgusted by the farce than by the lack of action. Don't you have feedback buttons on the docs? What happens to the feedback from those? Please prove you consider feedback before asking people for more of it.
- perlwle 3y ago
  A few months ago I was working on migrating cloud build for a personal project and hit a documentation error. Submitted a correction via the feedback button and it got fixed few days later. To be honest I was a little surprised by how fast it got fixed.
dantiberian 3y ago
A general issue I have with GCP docs is that they are overly implicit. Often the interaction of two features is implied but not specified. Another issue I have is when implementation details are waved away rather than explained. It adds up to an experience where I am trying to read between the lines of the GCP docs for a feature to understand what is really happening. AWS docs are the opposite. They are often very long and verbose, but once you read the whole manual, you can be guaranteed to have a good understanding of the service. My advice for the Google team would be that if you are ever writing documentation and ask yourself “does the customer really need to know about this?”, the answer should always be yes.

aaarrm 3y ago

I've not used AWS but have been continuously curious if their docs are as scattered as GCP's, this is good to finally know.

adrr 3y ago

Google's support is the worst. Have an issue like those random nonsense error messages, good luck getting it resolved. AWS is complete the opposite. I had an issue Aurora Postgres and got to chat with the product manager of the product. Google could have the best products on the market but no one is going to use them if the support isn't there. I was sad when Looker got bought by google. I remember having issues with setting up looker and using their chat functionality and having the CEO of Looker answer my question.

latchkey 3y ago
> Google's support is the worst. 5 minutes later, the "technical writing manager on GCP", makes a helpful comment on this thread.
- mdaniel 3y ago
  Well, AIUI "reach the front page of HN" was always the only cited way of getting any help with a Google problem, so in that way this is a derivative of that scenario
  - mdhb 3y ago
    Also I never see this mentioned but just for anyone who isn’t clear… Google do actually offer great support, I pay like $30 a month for it and I can speak with real engineers who give super detailed answers. It’s just not free. But the paid offering is great in my experience.
    - _cenw 3y ago
      I've used GCP support on accounts with huge support contracts and enterprise agreements and it's still a bit of a wash if you get good support on your first, second or even third run around the reply button. At least it isn't (paid) Azure Support - that one is noticeably outsourced to people that sometimes lack basic comprehension for the problem. I once asked about their VPN Gateway and got a random API Gateway response, then nothing for a week, and then a new rep.

gorjusborg 3y ago

I had the same gripe when I worked with GCP. Their stuff is exotic, and had weird behaviors in corners, but the docs didn't give you enough context to steer away from them. However, over the last 5 years or so, AWS docs have gotten worse. So I guess now that they are both bad I can't complain?

denvrede 3y ago
Did they? Do you have an example at hand? We ran into "weird" issues a lot of times with AWS services just to discover afterwards that almost all of them were covered by their documentation. It was totally our fault and these were also no "hidden" docs.

slotrans 3y ago

Every GCP product is poorly documented. There are often no examples at all, and when there are they only cover the "hello world" case. Last I tried, the documented examples for Cloud Functions v2 simply did not work.