Skip to content
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

Jump to bottom

Document GPRC Connection's TLS option #1290

Merged
merged 6 commits into from
Aug 14, 2023
Merged

Document GPRC Connection's TLS option #1290

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
cb973dc
Document GPRC Connection's TLS option
olegbespalov Aug 9, 2023
b04ff59
Apply suggestions from code review
olegbespalov Aug 11, 2023
7baff9e
Update src/data/markdown/docs/02 javascript api/07 k6-experimental/02…
oleiade Aug 14, 2023
e06bfc1
Update src/data/markdown/docs/02 javascript api/11 k6-net-grpc/20 Cli…
oleiade Aug 14, 2023
1021f52
Update src/data/markdown/docs/02 javascript api/07 k6-experimental/02…
oleiade Aug 14, 2023
213ce62
Update src/data/markdown/docs/02 javascript api/11 k6-net-grpc/20 Cli…
mstoykov Aug 14, 2023
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
84 changes: 82 additions & 2 deletions ...7 k6-experimental/02 grpc/20 Client/20-Client-connect-connect-address-params.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,20 @@ See [Client.close()](/javascript-api/k6-experimental/grpc/client/client-close) t
| `ConnectParams.plaintext` | bool | If `true` will connect to the gRPC server using plaintext i.e. insecure. Defaults to `false` i.e. secure via TLS. |
| `ConnectParams.reflect` | boolean | Whether to use the [gRPC server reflection protocol](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md) when connecting. |
| `ConnectParams.timeout` | string / number | Connection timeout to use. Default timeout is `"60s"`. <br/> The type can also be a number, in which case k6 interprets it as milliseconds, e.g., `60000` is equivalent to `"60s"`. |
| `ConnectParams.maxReceiveSize` | number | Sets the maximum message size in bytes the client can receive.Defaults to 0. |
| `ConnectParams.maxSendSize` | number | Sets the maximum message size in bytes the client can send.Defaults to 0. |
| `ConnectParams.maxReceiveSize` | number | Sets the maximum message size in bytes the client can receive. Defaults to 0. |
| `ConnectParams.maxSendSize` | number | Sets the maximum message size in bytes the client can send. Defaults to 0. |
| `ConnectParams.tls` (optional) | object | [TLS](#tls) settings of the connection. Defaults to `null`. |

## TLS

TLS settings of the connection. If not defined, the main TLS config from options will be used.

| Name | Type | Description |
|------|------|-------------|
| `tls.cert` | string | PEM formatted client certificate. |
| `tls.key` | string | PEM formatted client private key. |
| `tls.password` | string | Password for decrypting the client's private key. |
| `tls.cacerts` | string / array | PEM formatted strings of the certificate authorities. |

### Examples

Expand Down Expand Up @@ -50,3 +62,71 @@ export default () => {
};
```
</div>

<div class="code-group" data-props='{"labels": ["Different TLS settings"], "lineNumbers": [true]}'>

```javascript
import grpc from 'k6/experimental/grpc';
import { check } from 'k6';

// note: the services in this example don't exist. If you would like
// to run this example, make sure to replace the URLs, and
// the cacerts, cert, key, and password variables.
const params = {
'foo1.grpcbin.test.k6.io:9001': {
plaintext: false,
tls: {
cacerts: [open('cacerts0.pem')],
cert: open('cert0.pem'),
key: open('key0.pem'),
},
},
'foo2.grpcbin.test.k6.io:9002': {
plaintext: false,
tls: {
cacerts: open('cacerts1.pem'),
cert: open('cert1.pem'),
key: open('key1.pem'),
password: 'cert1-passphrase',
},
},
};
Copy link
Contributor

Choose a reason for hiding this comment

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

This was briefly discussed in the original PR - the certificates and keys are likely going to be big enough that loading each and everyone for each VU will be wasteful.

As such I would recommend using SharedArray to anyone who will use this to have different certificates per connection/VU.

I would also prefer if any examples we provide follow this advice as users commonly copy paste examples as-is.

const clients = {
'foo1.grpcbin.test.k6.io:9001': new grpc.Client(),
'foo2.grpcbin.test.k6.io:9002': new grpc.Client(),
};

export default () => {
if (__ITER === 0) {
clients['foo1.grpcbin.test.k6.io:9001'].connect(
'foo1.grpcbin.test.k6.io:9001',
params['foo1.grpcbin.test.k6.io:9001']
);
clients['foo2.grpcbin.test.k6.io:9002'].connect(
'foo2.grpcbin.test.k6.io:9002',
params['foo2.grpcbin.test.k6.io:9002']
);
}

const response1 = clients['foo1.grpcbin.test.k6.io:9001'].invoke('hello.HelloService/SayHello', {
greeting: 'Bert',
});

check(response1, {
'status is OK': (r) => r && r.status === grpc.StatusOK,
});

console.log(JSON.stringify(response1.message));

const response2 = clients['foo2.grpcbin.test.k6.io:9002'].invoke('hello.HelloService/SayHello', {
greeting: 'Ernie',
});

check(response2, {
'status is OK': (r) => r && r.status === grpc.StatusOK,
});

console.log(JSON.stringify(response2.message));
};
oleiade marked this conversation as resolved.
Show resolved Hide resolved
```
</div>
82 changes: 80 additions & 2 deletions ...script api/11 k6-net-grpc/20 Client/20-Client-connect-connect-address-params.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,20 @@ See [Client.close()](/javascript-api/k6-net-grpc/client/client-close) to close t
| `ConnectParams.plaintext` | bool | If `true` will connect to the gRPC server using plaintext i.e. insecure. Defaults to `false` i.e. secure via TLS. |
| `ConnectParams.reflect` | boolean | Whether to use the [gRPC server reflection protocol](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md) when connecting. |
| `ConnectParams.timeout` | string / number | Connection timeout to use. Default timeout is `"60s"`. <br/> The type can also be a number, in which case k6 interprets it as milliseconds, e.g., `60000` is equivalent to `"60s"`. |
| `ConnectParams.maxReceiveSize` | number | Sets the maximum message size in bytes the client can receive.Defaults to 0. |
| `ConnectParams.maxSendSize` | number | Sets the maximum message size in bytes the client can send.Defaults to 0. |
| `ConnectParams.maxReceiveSize` | number | Sets the maximum message size in bytes the client can receive. Defaults to 0. |
| `ConnectParams.maxSendSize` | number | Sets the maximum message size in bytes the client can send. Defaults to 0. |
| `ConnectParams.tls` (optional) | object | [TLS](#tls) settings of the connection. Defaults to `null`. |

## TLS

TLS settings of the connection. If not defined, the main TLS config from options will be used.

| Name | Type | Description |
|------|------|-------------|
| `tls.cert` | string | PEM formatted client certificate. |
| `tls.key` | string | PEM formatted client private key. |
| `tls.password` | string | Password for decrypting the client's private key. |
| `tls.cacerts` | string / array | PEM formatted strings of the certificate authorities. |

### Examples

Expand Down Expand Up @@ -50,3 +62,69 @@ export default () => {
};
```
</div>

<div class="code-group" data-props='{"labels": ["Different TLS settings"], "lineNumbers": [true]}'>

```javascript
import grpc from 'k6/net/grpc';
import { check } from 'k6';

// note: there are no such services
const params = {
'foo1.grpcbin.test.k6.io:9001': {
plaintext: false,
tls: {
cacerts: [open('cacerts0.pem')],
cert: open('cert0.pem'),
key: open('key0.pem'),
},
},
'foo2.grpcbin.test.k6.io:9002': {
plaintext: false,
tls: {
cacerts: open('cacerts1.pem'),
cert: open('cert1.pem'),
key: open('key1.pem'),
password: 'cert1-passphrase',
},
},
};
const clients = {
'foo1.grpcbin.test.k6.io:9001': new grpc.Client(),
'foo2.grpcbin.test.k6.io:9002': new grpc.Client(),
};

export default () => {
if (__ITER === 0) {
clients['foo1.grpcbin.test.k6.io:9001'].connect(
'foo1.grpcbin.test.k6.io:9001',
params['foo1.grpcbin.test.k6.io:9001']
);
clients['foo2.grpcbin.test.k6.io:9002'].connect(
'foo2.grpcbin.test.k6.io:9002',
params['foo2.grpcbin.test.k6.io:9002']
);
}

const response1 = clients['foo1.grpcbin.test.k6.io:9001'].invoke('hello.HelloService/SayHello', {
greeting: 'Bert',
});

check(response1, {
'status is OK': (r) => r && r.status === grpc.StatusOK,
});

console.log(JSON.stringify(response1.message));

const response2 = clients['foo2.grpcbin.test.k6.io:9002'].invoke('hello.HelloService/SayHello', {
greeting: 'Ernie',
});

check(response2, {
'status is OK': (r) => r && r.status === grpc.StatusOK,
});

console.log(JSON.stringify(response2.message));
};
oleiade marked this conversation as resolved.
Show resolved Hide resolved
```
</div>
Loading