Improve documentation

[averikitsch]

This library has no documentation beyond the README, not even in the source code. It's hard to know the difference between methods like: gcpMetadata.project() and gcpMetadata.instance(). It also leads me to question: Do I have to pass the project-id into project() in order to get my project id?

const projectId = await gcpMetadata.project('project-id');
console.log(projectId); // ...Project ID of the running instance

Is your feature request related to a problem? Please describe.
Need more guidance on using this library.

Describe the solution you'd like
Reference docs or better examples and samples. Links to info on the metadata server would be nice as well.

[grant]

Is this module available for other languages as well? I'm trying to create a sample, but am not sure if I can use this library in other languages besides Node. Or if this library is not recommended for simple use-cases like getting the project ID.

[averikitsch]

Is this module available for other languages as well? I'm trying to create a sample, but am not sure if I can use this library in other languages besides Node. Or if this library is not recommended for simple use-cases like getting the project ID.

I haven't been able to find anything similar for other languages besides the google auth libraries. It seems functionality with that library also varies between languages.

[JustinBeckwith]

Hey folks! Answering a few of these:

It's hard to know the difference between methods like: gcpMetadata.project() and gcpMetadata.instance()

So, for the difference between .instance() and .project() it's mostly just exposing the different end points that are available here:
https://cloud.google.com/compute/docs/storing-retrieving-metadata#project-instance-metadata

Do I have to pass the project-id into project() in order to get my project id?
Nope! It gets the project Id from the current executing environment automatically. You should be able to do something like this:

const projectId = await gcpMetadata.project('project-id');

The magic project-id path thing is from here:
https://cloud.google.com/compute/docs/metadata/default-metadata-values#project_metadata

In 99% of cases though, you wouldn't want to do this - you generally want to use the more generic auth.getProjectId() that's described here:
https://github.com/googleapis/google-auth-library-nodejs/#choosing-the-correct-credential-type-automatically

google-auth-library will do all the magic to check env vars, local credentials, and only finally the metadata server.

So on documentation - we have reference documentation, it's just not linked from the README right now 🤦‍♂️
https://googleapis.dev/nodejs/gcp-metadata/latest/miscellaneous/functions.html#project

I have a PR here to at least bring the README closer to what's happening elsewhere.

Is this module available for other languages as well? I'm trying to create a sample, but am not sure if I can use this library in other languages besides Node. Or if this library is not recommended for simple use-cases like getting the project ID.

I don't believe other languages chose to split this functionality out, and rather integrated it into their authentication libraries. Not sure if that's a good or bad thing :)

[danielbankhead]

The docs look improved since this issue was filed. Feel free to reopen if you need anything else!