Merge pull request #1276 from grafana/aws/v0.9.0

Update documentation to include changes in aws jslib v0.9.0

Author: oleiade

src/components/shared/blocking-aws-blockquote/blocking-aws-blockquote.view.js

@@ -6,19 +6,15 @@ const BlockingAwsBlockquote = () => (
     mod="Attention"
     title="Performance considerations and recommended practices"
   >
-    The APIs provided by this jslib operate synchronously, which means k6 must
-    wait for operations that use the client classes to finish before proceeding
-    with the rest of the script.
-    <p>
-      In some cases, such as downloading large files from S3, this could affect
-      performance and test results. To minimize the impact on test performance,
-      we recommend using these operations in the
-      <span className="code-inline">setup</span> and{' '}
-      <span className="code-inline">teardown</span>{' '}
-      <a href="/docs/using-k6/test-lifecycle/">lifecycle functions</a>. These
-      functions run before and after the test run and thus do not influence test
-      results.
-    </p>
+    In some cases, using this library&apos;s operations might impact performance
+    and skew your test results. <br />
+    <br />
+    To ensure accurate results, consider executing these operations in the{' '}
+    <span className="code-inline">setup</span> and{' '}
+    <span className="code-inline">teardown</span>{' '}
+    <a href="/docs/using-k6/test-lifecycle/">lifecycle functions</a>. These
+    functions run before and after the test run and have no impact on the test
+    results.
   </Blockquote>
 );
 

src/data/markdown/docs/05 Examples/01 Examples/02 http-authentication.md

@@ -118,7 +118,7 @@ Here's an example script to demonstrate how to sign a request to fetch an object
 
 ```javascript
 import http from 'k6/http';
-import { AWSConfig, SignatureV4 } from 'https://jslib.k6.io/aws/0.8.1/signature.js';
+import { AWSConfig, SignatureV4 } from 'https://jslib.k6.io/aws/0.9.0/signature.js';
 
 const awsConfig = new AWSConfig({
     region: __ENV.AWS_REGION,

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 AwsConfig.md

@@ -41,7 +41,7 @@ import exec from 'k6/execution';
 
 // Note that you AWSConfig is also included in the dedicated service
 // client bundles such as `s3.js` and `secrets-manager.js`
-import { AWSConfig, SecretsManagerClient } from 'https://jslib.k6.io/aws/0.8.1/aws.js';
+import { AWSConfig, SecretsManagerClient } from 'https://jslib.k6.io/aws/0.9.0/aws.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 KMSClient.md

@@ -8,7 +8,8 @@ excerpt: 'KMSClient allows interacting with the AWS Key Management Service'
 <BlockingAwsBlockquote />
 
 `KMSClient` interacts with the AWS Key Management Service.
-With it, the user can list all the Key Management Service keys in the caller's AWS account and region. They can also generate symmetric data keys to use outside of AWS Key Management Service. `KMSClient` operations are blocking. k6 recommends reserving their use to the [`setup`](/using-k6/test-lifecycle/) and [`teardown`](/using-k6/test-lifecycle/) stages as much as possible.
+
+With it, the user can list all the Key Management Service keys in the caller's AWS account and region. They can also generate symmetric data keys to use outside of AWS Key Management Service.
 
 Both the dedicated `kms.js` jslib bundle and the all-encompassing `aws.js` bundle include the `KMSClient`.
 
@@ -35,7 +36,7 @@ Both the dedicated `kms.js` jslib bundle and the all-encompassing `aws.js` bundl
 ```javascript
 import { textSummary } from 'https://jslib.k6.io/k6-summary/0.0.2/index.js';
 
-import { AWSConfig, KMSClient } from 'https://jslib.k6.io/aws/0.8.1/kms.js';
+import { AWSConfig, KMSClient } from 'https://jslib.k6.io/aws/0.9.0/kms.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,
@@ -46,14 +47,14 @@ const awsConfig = new AWSConfig({
 const kms = new KMSClient(awsConfig);
 const keyAlias = 'alias/k6-key';
 
-export function setup() {
+export async function setup() {
   // Create a symmetric data key
   return {
-    dataKey: kms.generateDataKey(keyAlias, 32),
+    dataKey: await kms.generateDataKey(keyAlias, 32),
   };
 }
 
-export default function (data) {
+export default async function (data) {
   // Use the data key to encrypt data
 }
 

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 S3Client.md

@@ -7,9 +7,11 @@ excerpt: 'S3Client class allows interacting with AWS S3 buckets and objects'
 
 <BlockingAwsBlockquote />
 
-S3Client allows interacting with AWS S3's buckets and objects. Namely, it allows the user to list buckets and the objects they contain, as well as download, uploading, and deleting objects. The S3Client operations are blocking, and we recommend reserving their usage to the [`setup`](/using-k6/test-lifecycle/) and [`teardown`](/using-k6/test-lifecycle/) functions as much as possible.
+`S3Client` interacts with the AWS Simple Storage Service (S3).
 
-S3Client is included in both the dedicated jslib `s3.js` bundle, and the `aws.js` one, containing all the services clients.
+With it, you can do several operations such as list buckets, list objects in a bucket, or download objects from a bucket. For a full list of supported operations, see [Methods](#methods).
+
+Both the dedicated `s3.js` jslib bundle and the all-encompassing `aws.js` bundle include the `S3Client`.
 
 ### Methods
 
@@ -44,7 +46,7 @@ import { check } from 'k6';
 import exec from 'k6/execution';
 import http from 'k6/http';
 
-import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.8.1/s3.js';
+import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.9.0/s3.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,
@@ -57,21 +59,21 @@ const testBucketName = 'test-jslib-aws';
 const testInputFileKey = 'productIDs.json';
 const testOutputFileKey = `results-${Date.now()}.json`;
 
-export function setup() {
+export async function setup() {
   // If our test bucket does not exist, abort the execution.
-  const buckets = s3.listBuckets();
+  const buckets = await s3.listBuckets();
   if (buckets.filter((b) => b.name === testBucketName).length == 0) {
     exec.test.abort();
   }
 
   // If our test object does not exist, abort the execution.
-  const objects = s3.listObjects(testBucketName);
+  const objects = await s3.listObjects(testBucketName);
   if (objects.filter((o) => o.key === testInputFileKey).length == 0) {
     exec.test.abort();
   }
 
   // Download the S3 object containing our test data
-  const inputObject = s3.getObject(testBucketName, testInputFileKey);
+  const inputObject = await s3.getObject(testBucketName, testInputFileKey);
 
   // Let's return the downloaded S3 object's data from the
   // setup function to allow the default function to use it.
@@ -80,31 +82,33 @@ export function setup() {
   };
 }
 
-export default function (data) {
+export default async function (data) {
   // Pick a random product ID from our test data
   const randomProductID = data.productIDs[Math.floor(Math.random() * data.productIDs.length)];
 
   // Query our ecommerce website's product page using the ID
-  const res = http.get(`http://your.website.com/product/${randomProductID}/`);
+  const res = await http.asyncRequest("GET", `http://your.website.com/product/${randomProductID}/`);
   check(res, { 'is status 200': res.status === 200 });
 }
 
-export function handleSummary(data) {
+export async function handleSummary(data) {
   // Once the load test is over, let's upload the results to our
   // S3 bucket. This is executed after teardown.
-  s3.putObject(testBucketName, testOutputFileKey, JSON.stringify(data));
+  await s3.putObject(testBucketName, testOutputFileKey, JSON.stringify(data));
 }
 ```
 
 </CodeGroup>
 
+#### Multipart uploads
+
 <CodeGroup labels={[]}>
 
 ```javascript
 import crypto from 'k6/crypto';
 import exec from 'k6/execution';
 
-import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.8.1/s3.js';
+import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.9.0/s3.js';
 
 const awsConfig = new AWSConfig({
     region: __ENV.AWS_REGION,
@@ -118,10 +122,10 @@ const s3 = new S3Client(awsConfig);
 const testBucketName = 'test-jslib-aws';
 const testFileKey = 'multipart.txt';
 
-export default function () {
+export default async function () {
     // List the buckets the AWS authentication configuration
     // gives us access to.
-    const buckets = s3.listBuckets();
+    const buckets = await s3.listBuckets();
 
     // If our test bucket does not exist, abort the execution.
     if (buckets.filter((b) => b.name === testBucketName).length == 0) {
@@ -134,11 +138,11 @@ export default function () {
     const bigFile = crypto.randomBytes(12 * 1024 * 1024);
 
     // Initialize a multipart upload
-    const multipartUpload = s3.createMultipartUpload(testBucketName, testFileKey);
+    const multipartUpload = await s3.createMultipartUpload(testBucketName, testFileKey);
 
     // Upload the first part
     const firstPartData = bigFile.slice(0, 6 * 1024 * 1024);
-    const firstPart = s3.uploadPart(
+    const firstPart = await s3.uploadPart(
         testBucketName,
         testFileKey,
         multipartUpload.uploadId,
@@ -148,7 +152,7 @@ export default function () {
 
     // Upload the second part
     const secondPartData = bigFile.slice(6 * 1024 * 1024, 12 * 1024 * 1024);
-    const secondPart = s3.uploadPart(
+    const secondPart = await s3.uploadPart(
         testBucketName,
         testFileKey,
         multipartUpload.uploadId,
@@ -157,14 +161,14 @@ export default function () {
     );
 
     // Complete the multipart upload
-    s3.completeMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId, [
+    await s3.completeMultipartUpload(testBucketName, testFileKey, multipartUpload.uploadId, [
         firstPart,
         secondPart,
     ]);
 
     // Let's redownload it verify it's correct, and delete it
-    const obj = s3.getObject(testBucketName, testFileKey);
-    s3.deleteObject(testBucketName, testFileKey);
+    const obj = await s3.getObject(testBucketName, testFileKey);
+    await s3.deleteObject(testBucketName, testFileKey);
 }
 ```
 

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 SQSClient.md

@@ -5,11 +5,11 @@ description: 'SQSClient enables interaction with the AWS Simple Queue Service (S
 excerpt: 'SQSClient allows interacting with the AWS Simple Queue Service (SQS)'
 ---
 
-<BlockingAwsBlockquote />
+`SQSClient` interacts with the AWS Simple Queue Service (SQS).
 
-`SQSClient` interacts with the AWS Simple Queue Service (SQS). With it, the user can send messages to specified queues and list available queues in the current region. `SQSClient` operations are blocking.
+With it, the user can send messages to specified queues and list available queues in the current region.
 
-Both the dedicated `sqs.js` jslib bundle and the all-encompassing `aws.js` bundle include the `SQSClient`.
+`SQSClient` is included in both the dedicated `sqs.js` jslib bundle and the all-encompassing `aws.js` one, containing all the services clients.
 
 ### Methods
 
@@ -34,7 +34,7 @@ Both the dedicated `sqs.js` jslib bundle and the all-encompassing `aws.js` bundl
 ```javascript
 import exec from 'k6/execution'
 
-import { AWSConfig, SQSClient } from 'https://jslib.k6.io/aws/0.8.1/sqs.js'
+import { AWSConfig, SQSClient } from 'https://jslib.k6.io/aws/0.9.0/sqs.js'
 
 const awsConfig = new AWSConfig({
     region: __ENV.AWS_REGION,
@@ -46,15 +46,15 @@ const awsConfig = new AWSConfig({
 const sqs = new SQSClient(awsConfig)
 const testQueue = 'https://sqs.us-east-1.amazonaws.com/000000000/test-queue'
 
-export default function () {
+export default async function () {
     // If our test queue does not exist, abort the execution.
-    const queuesResponse = sqs.listQueues()
+    const queuesResponse = await sqs.listQueues()
     if (queuesResponse.queueUrls.filter((q) => q === testQueue).length == 0) {
         exec.test.abort()
     }
 
     // Send message to test queue
-    sqs.sendMessage(testQueue, JSON.stringify({value: '123'}));
+    await sqs.sendMessage(testQueue, JSON.stringify({value: '123'}));
 }
 ```
 

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 SecretsManagerClient.md

@@ -5,11 +5,11 @@ description: 'SecretsManagerClient allows interacting with AWS secrets stored in
 excerpt: 'SecretsManagerClient allows interacting with AWS secrets stored in Secrets Manager'
 ---
 
-<BlockingAwsBlockquote />
+`SecretsManagerClient` interacts with the AWS Secrets Manager.
 
-SecretsManagerClient allows interacting with secrets stored in AWS's Secrets Manager. Namely, it allows the user to list, download, create, modify and delete secrets. Note that the SecretsManagerClient operations are blocking, and we recommend reserving their usage to the [`setup`](/using-k6/test-lifecycle/) and [`teardown`](/using-k6/test-lifecycle/) functions as much as possible.
+With it, you can perform several operations such as listing, creating and downloading secrets owned by the authenticated user. For a full list of supported operations, see [Methods](#methods).
 
-SecretsManagerClient is included in both the dedicated jslib `secrets-manager.js` bundle, and the `aws.js` one, containing all the services clients.
+`SecretsManagerClient` is included in both the dedicated jslib `secrets-manager.js` bundle, and the `aws.js` one, containing all the services clients.
 
 ### Methods
 
@@ -37,7 +37,7 @@ S3 Client methods will throw errors in case of failure.
 ```javascript
 import exec from 'k6/execution';
 
-import { AWSConfig, SecretsManagerClient } from 'https://jslib.k6.io/aws/0.8.1/secrets-manager.js';
+import { AWSConfig, SecretsManagerClient } from 'https://jslib.k6.io/aws/0.9.0/secrets-manager.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,
@@ -49,39 +49,39 @@ const secretsManager = new SecretsManagerClient(awsConfig);
 const testSecretName = 'jslib-test-secret';
 const testSecretValue = 'jslib-test-value';
 
-export function setup() {
+export async function setup() {
   // Let's make sure our test secret is created
-  const testSecret = secretsManager.createSecret(
+  const testSecret = await secretsManager.createSecret(
     testSecretName,
     testSecretValue,
     'this is a test secret, delete me.'
   );
 
   // List the secrets the AWS authentication configuration
   // gives us access to, and verify the creation was successful.
-  const secrets = secretsManager.listSecrets();
+  const secrets = await secretsManager.listSecrets();
   if (!secrets.filter((s) => s.name === testSecret.name).length == 0) {
     exec.test.abort('test secret not found');
   }
 }
 
-export default function () {
+export default async function () {
   // Knnowing that we know the secret exist, let's update its value
   const newTestSecretValue = 'new-test-value';
-  secretsManager.putSecretValue(testSecretName, newTestSecretValue);
+  await secretsManager.putSecretValue(testSecretName, newTestSecretValue);
 
   // Let's get its value and verify it was indeed updated
-  const updatedSecret = secretsManager.getSecret(testSecretName);
+  const updatedSecret = await secretsManager.getSecret(testSecretName);
   if (updatedSecret.secret !== newTestSecretValue) {
     exec.test.abort('unable to update test secret');
   }
 
   // Let's now use our secret in the context of our load test...
 }
 
-export function teardown() {
+export async function teardown() {
   // Finally, let's clean after ourselves and delete our test secret
-  secretsManager.deleteSecret(testSecretName, { noRecovery: true });
+  await secretsManager.deleteSecret(testSecretName, { noRecovery: true });
 }
 ```
 

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 SignatureV4.md

@@ -5,6 +5,8 @@ description: 'SignatureV4 is used to sign or pre-sign requests to AWS services u
 excerpt: 'SignatureV4 is used to sign and pre-sign requests to AWS services using the Signature V4 algorithm'
 ---
 
+<BlockingAwsBlockquote />
+
 With SignatureV4, you can produce authenticated HTTP requests to AWS services. Namely, it lets you sign and pre-sign requests to AWS services using the [Signature V4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) algorithm. The `sign` operation produces a signed request with authorization information stored in its headers.
 The `presign` operation produces a pre-signed request with authorization information stored in its query string parameters.
 
@@ -42,9 +44,9 @@ SignatureV4 methods throw errors on failure.
 <CodeGroup labels={[]}>
 
 ```javascript
-import http from 'k6/http.js'
+import http from 'k6/http'
 
-import { AWSConfig, SignatureV4 } from 'https://jslib.k6.io/aws/0.8.1/aws.js'
+import { AWSConfig, SignatureV4 } from 'https://jslib.k6.io/aws/0.9.0/aws.js'
 
 const awsConfig = new AWSConfig({
     region: __ENV.AWS_REGION,