Skip to content

TLS settings for gRPC #10653

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Aug 11, 2025
Merged

TLS settings for gRPC #10653

Changes from 7 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
576d4b3
Add gRPC tls settings.
finnegancarroll Aug 5, 2025
cb1baae
Update _security/configuration/tls.md
finnegancarroll Aug 7, 2025
733d35e
Update _security/configuration/tls.md
finnegancarroll Aug 7, 2025
7ca74cf
Update _security/configuration/tls.md
finnegancarroll Aug 7, 2025
1bb10fa
Update _security/configuration/tls.md
finnegancarroll Aug 7, 2025
7fa2d49
Update _security/configuration/tls.md
finnegancarroll Aug 7, 2025
b725a05
Update _security/configuration/tls.md
finnegancarroll Aug 7, 2025
b205313
Update _security/configuration/tls.md
finnegancarroll Aug 8, 2025
3bc4749
Update _security/configuration/tls.md
finnegancarroll Aug 8, 2025
d089938
Update _security/configuration/tls.md
finnegancarroll Aug 8, 2025
499e216
Update _security/configuration/tls.md
finnegancarroll Aug 8, 2025
1e997ec
Fix gRPC heading level -> 2.
finnegancarroll Aug 8, 2025
db84bc0
Clarify keystore/trusstore alias behavior.
finnegancarroll Aug 8, 2025
fbbae0b
Apply suggestions from code review
kolchfa-aws Aug 11, 2025
498295a
Apply suggestions from code review
natebower Aug 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions _security/configuration/tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -310,6 +310,35 @@
{ "message": "successfully updated http certs"}
```

#### Configuring TLS certificates for gRPC

gRPC supports encryption in transit only. Trust stores and certificates configured as root CAs in PEM format are used only for the purpose of TLS client authorization. Role-based access is not available for gRPC endpoints.
{: .warning}

You can configure TLSon the optional gRPC transport in `opensearch.yml`. For more information about using gRPC plugin, see [Enabling the plugin]({{site.url}}{{site.baseurl}}/api-reference/grpc-apis/index/#enabling-the-plugin).

Check failure on line 318 in _security/configuration/tls.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.SpacingWords] There should be one space between words in 'using gRPC'.

Raw Output:
{"message": "[OpenSearch.SpacingWords] There should be one space between words in 'using gRPC'.", "location": {"path": "_security/configuration/tls.md", "range": {"start": {"line": 318, "column": 101}}}, "severity": "ERROR"}

Check failure on line 318 in _security/configuration/tls.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: TLSon. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: TLSon. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_security/configuration/tls.md", "range": {"start": {"line": 318, "column": 19}}}, "severity": "ERROR"}

### Pemkey settings (X.509 PEM certificates and PKCS #8 keys)

Check failure on line 320 in _security/configuration/tls.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: Pemkey. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: Pemkey. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_security/configuration/tls.md", "range": {"start": {"line": 320, "column": 5}}}, "severity": "ERROR"}

The following table lists the available gRPC PEM key settings.

Name | Description
:--- | :---
`plugins.security.ssl.aux.secure-transport-grpc.enabled` | Whether to enable TLS for gRPC. If enabled, only HTTPS is allowed. Optional. Default is `false`.
`plugins.security.ssl.aux.secure-transport-grpc.pemkey_filepath` | The path to the certificate's key file (PKCS #8), specified as a relative path from the `config` directory. The file must reside within the `config` directory. Required.
`plugins.security.ssl.aux.secure-transport-grpc.pemkey_password` | The key password. Omit this setting if the key has no password. Optional.
`plugins.security.ssl.aux.secure-transport-grpc.pemcert_filepath` | Path to the X.509 node certificate chain (PEM format), which must be under the `config` directory, specified using a relative path. Required.
`plugins.security.ssl.aux.secure-transport-grpc.pemtrustedcas_filepath` | Path to the root CAs (PEM format), which must be under the `config` directory, specified using a relative path. Required.

### Keystore and trustore

Check failure on line 332 in _security/configuration/tls.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: trustore. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: trustore. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_security/configuration/tls.md", "range": {"start": {"line": 332, "column": 18}}}, "severity": "ERROR"}

Name | Description
:--- | :---
`plugins.security.ssl.aux.secure-transport-grpc.enabled` | Whether to enable TLS for gRPC. If enabled, only HTTPS is allowed. Optional. Default is `false`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`plugins.security.ssl.aux.secure-transport-grpc.enabled` | Whether to enable TLS for gRPC. If enabled, only HTTPS is allowed. Optional. Default is `false`.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking it makes sense to leave this in for both pem and keystore configurations. Regardless of the method users choose they will need this setting and so it might be confusing if it exists only under one section. Was following REST documentation which lists plugins.security.ssl.http.enabled under both pem and keystore sections.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, let's keep it here. My concern is if something changes, we'd need to update in two places, which is error-prone. We usually prefer to update in only one place.

`plugins.security.ssl.aux.secure-transport-grpc.keystore_type` | The type of the keystore file, JKS or PKCS12/PFX. Optional. Default is JKS.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this exactly. how you specify this? JKS, PKCS12, and PFX or should it be lowercase or any other variation? Please specify exactly like you'd need to specify and enclose in tic marks for code font.

Copy link
Contributor Author

@finnegancarroll finnegancarroll Aug 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All three are capitalized as they are acronyms. The grouping is because PKCS12 and PFX are different names for the same file format while JKS is a different format entirely. These settings are the same as existing REST TLS settings so I was following the descriptions/style given there.

`plugins.security.ssl.aux.secure-transport-grpc.keystore_filepath` | The path to the keystore file, specified as a relative path from the `config` directory. The file must reside within the `config` directory. Required.
`plugins.security.ssl.aux.secure-transport-grpc.keystore_alias` | The alias name of the keystore. Optional. Default is the first alias.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you add more information - what does "the first" mean in this context?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The keystore configured with the above ...grpc.keystore_filepathcan contain several key-pairs each with different identifying names. If the user wants to use a specific key-pair they need to specify it here, otherwise the first key-pair which was added gets used.

Changed to these to clarify this:

`plugins.security.ssl.aux.secure-transport-grpc.keystore_alias` | The alias of the key-pair to use from the provided keystore. Optional. Defaults to the first key-pair added to the keystore.

`plugins.security.ssl.aux.secure-transport-grpc.truststore_alias` | The alias of the certificate to use from the provided truststore. Optional. Default is all certificates.

`plugins.security.ssl.aux.secure-transport-grpc.keystore_password` | The password for the keystore. Default is `changeit`.
`plugins.security.ssl.aux.secure-transport-grpc.truststore_type` | The type of the truststore file, JKS or PKCS12/PFX. Default is JKS.
`plugins.security.ssl.aux.secure-transport-grpc.truststore_filepath` | The path to the truststore file, , specified as a relative path from the `config` directory. The file must reside within the `config` directory. Required.
`plugins.security.ssl.aux.secure-transport-grpc.truststore_alias` | The alias name of the truststore. Optional. Default is all certificates.
`plugins.security.ssl.aux.secure-transport-grpc.truststore_password` | The password for the truststore. Default is `changeit`.
Loading