# synced-folder
A Pulumi component that synchronizes a local folder to Amazon S3, Azure Blob Storage, or Google Cloud Storage.
## Installing
The component is available in these Pulumi-supported languages:
* JavaScript/TypeScript: [`@pulumi/synced-folder`](https://www.npmjs.com/package/@pulumi/synced-folder)
* Python: [`pulumi_synced_folder`](https://pypi.org/project/pulumi-synced-folder/)
* Go: [`github.com/pulumi/pulumi-synced-folder/sdk/go/synced-folder`](https://github.com/pulumi/pulumi-synced-folder/)
* .NET: [`Pulumi.SyncedFolder`](https://www.nuget.org/packages/Pulumi.SyncedFolder)
* YAML
## Using the component
Given a cloud-storage bucket and the path to a local folder, the component synchronizes files from the folder to the bucket, deleting any files in the destination bucket that don't exist locally. It does this in one of two ways:
* By managing each file as an individual Pulumi resource (`aws.s3.BucketObject`, `azure.storage.Blob`, or `gcp.storage.BucketObject`). This is the component's default behavior.
* By delegating sync responsibility to a cloud provider CLI (e.g., [`aws`](https://aws.amazon.com/cli/), [`az`](https://docs.microsoft.com/en-us/cli/azure/), or [`gcloud`/`gsutil`](https://cloud.google.com/storage/docs/gsutil)). This behavior is enabled by setting the `managedObjects` input property to `false` and ensuring the relevant CLI tool is installed alongside `pulumi`.
The former approach — having Pulumi manage your resources for you — is generally preferable, but in some cases, for example a website consisting of thousands of files, it may not be the best fit. This component lets you choose the approach that works best for you, without having to brek out of your Pulumi program or workflow.
Below are a few examples in Pulumi YAML, each of which assumes the existence of a `site` folder containing one or more files to be uploaded. See the [examples](./examples) folder for additional languages and scenarios.
### Sync to an S3 bucket
Here, a local folder, `./site`, is pushed to Amazon S3, its contents managed as individual `s3.BucketObject`s:
```yaml
name: synced-folder-examples-aws-yaml
runtime: yaml
description: An example of using the synced-folder component.
resources:
s3-bucket:
type: aws:s3:Bucket
properties:
acl: public-read
website:
indexDocument: index.html
errorDocument: error.html
# 👇
synced-bucket-folder:
type: synced-folder:index:S3BucketFolder
properties:
path: ./site
bucketName: ${s3-bucket.bucket}
acl: public-read
outputs:
url: http://${s3-bucket.websiteEndpoint}
```
### Sync to an Azure Blob Storage container
Here, the folder's contents are synced to an Azure Blob Storage container, but instead of managing each file as an `azure.storage.Blob`, the component invokes the Azure CLI (specifically the `az storage blob sync` command) with [Pulumi Command](https://www.pulumi.com/registry/packages/command/). The optional `managedObjects` property lets you configure this behavior on a folder-by-folder basis.
```yaml
name: synced-folder-examples-azure-yaml
runtime: yaml
description: An example of using the synced-folder component in YAML.
resources:
resource-group:
type: azure-native:resources:ResourceGroup
storage:
type: azure-native:storage:StorageAccount
properties:
resourceGroupName: ${resource-group.name}
kind: StorageV2
sku:
name: Standard_LRS
website:
type: azure-native:storage:StorageAccountStaticWebsite
properties:
resourceGroupName: ${resource-group.name}
accountName: ${storage.name}
indexDocument: index.html
error404Document: error.html
# 👇
synced-azure-blob-folder:
type: synced-folder:index:AzureBlobFolder
properties:
path: ./site
resourceGroupName: ${resource-group.name}
storageAccountName: ${storage.name}
containerName: ${website.containerName}
managedObjects: false # 👈 Sync files with the Azure CLI.
outputs:
url: ${storage.primaryEndpoints.web}
```
### Sync to a Google Cloud Storage bucket
Here, `./site` is synced to a Google Cloud Storage bucket.
```yaml
name: synced-folder-examples-google-cloud-yaml
runtime: yaml
description: An example of using the synced-folder component in YAML.
resources:
gcp-bucket:
type: gcp:storage:Bucket
properties:
location: US
website:
mainPageSuffix: index.html
notFoundPage: error.html
gcp-bucket-iam-binding:
type: gcp:storage:BucketIAMBinding
properties:
bucket: ${gcp-bucket.name}
role: roles/storage.objectViewer
members:
- allUsers
# 👇
synced-google-cloud-folder:
type: synced-folder:index:GoogleCloudFolder
properties:
path: ./site
bucketName: ${gcp-bucket.name}
outputs:
url: https://storage.googleapis.com/${gcp-bucket.name}/index.html
```
## Configuration
The following input properties are common to all three resource types:
| Property | Type | Description |
| -------- | ---- | ----------- |
| `path` | `string` | The path (relative or fully-qualified) to the folder containing the files to be synced. Required. |
| `managedObjects` | `boolean` | Whether to have Pulumi manage files as individual cloud resources. Defaults to `true`. See below for details. |
Additional resource-specific properties are listed below.
### `S3BucketFolder` properties
| Property | Type | Description |
| -------- | ---- | ----------- |
| `bucketName` | `string` | The name of the S3 bucket to sync to (e.g., `my-bucket` in `s3://my-bucket`). Required. |
| `acl` | `string` | The AWS [Canned ACL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl) to apply to each file (e.g., `public-read`). Required. |
### `AzureBlobFolder` properties
| Property | Type | Description |
| -------- | ---- | ----------- |
| `containerName` | `string` | The name of the Azure storage container to sync to. Required. |
| `storageAccountName` | `string` | The name of the Azure storage account that the container belongs to. Required. |
| `resourceGroupName` | `string` | The name of the Azure resource group that the storage account belongs to. Required. |
### `GoogleCloudFolder` properties
| Property | Type | Description |
| -------- | ---- | ----------- |
| `bucketName` | `string` | The name of the Google Cloud Storage bucket to sync to (e.g., `my-bucket` in `gs://my-bucket`). Required. |
## Notes
### Using the `managedObjects` property
By default, the component manages your files as individual Pulumi cloud resources, but you can opt out of this behavior by setting the component's `managedObjects` property to `false`. When you do this, the component assumes you've installed the appropriate CLI tool — [`aws`](https://aws.amazon.com/cli/), [`az`](https://docs.microsoft.com/en-us/cli/azure/), or [`gcloud`/`gsutil`](https://cloud.google.com/storage/docs/gsutil), depending on the cloud — and uses the [Command](https://www.pulumi.com/registry/packages/command/) provider to issue commands on that tool directly. Files are one-way synchronized only (local to remote), and files that exist remotely but not locally are deleted. All files are deleted from remote storage on `pulumi destroy`.
The component does not yet support switching seamlessly between `managedObjects: true` and `managedObjects: false`, however, so if you find after deploying a given folder with managed objects that you'd prefer to use unmanaged objects instead (or vice-versa), we recommend creating a second bucket/storage container and folder and removing the first. You can generally do this within the scope of a single program update. For example:
```yaml
# ...
resources:
# The original bucket and synced-folder resources, using managed file objects.
#
# my-first-bucket:
# type: aws:s3:Bucket
# properties:
# acl: public-read
# website:
# indexDocument: index.html
# errorDocument: error.html
#
# my-first-synced-folder:
# type: synced-folder:index:S3BucketFolder
# properties:
# path: ./stuff
# bucketName: ${my-first-bucket.bucket}
# acl: public-read
# A new bucket and synced-folder using unmanaged file objects.
changed-my-mind-bucket:
type: aws:s3:Bucket
properties:
acl: public-read
website:
indexDocument: index.html
errorDocument: error.html
changed-my-mind-synced-folder:
type: synced-folder:index:S3BucketFolder
properties:
path: ./stuff
bucketName: ${changed-my-mind-bucket.bucket}
acl: public-read
managedObjects: false
outputs:
# An updated program reference pointing to the new bucket.
url: http://${changed-my-mind-bucket.websiteEndpoint}
```
Raw data
{
"_id": null,
"home_page": "https://pulumi.com",
"name": "pulumi-synced-folder",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "pulumi aws azure gcp category/cloud kind/component",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/72/eb/0c44399b45ef1ec3a2137ff02947248d4c2b6296b37be77165751956b0a2/pulumi_synced_folder-0.11.1.tar.gz",
"platform": null,
"description": "# synced-folder\n\nA Pulumi component that synchronizes a local folder to Amazon S3, Azure Blob Storage, or Google Cloud Storage.\n\n## Installing\n\nThe component is available in these Pulumi-supported languages:\n\n* JavaScript/TypeScript: [`@pulumi/synced-folder`](https://www.npmjs.com/package/@pulumi/synced-folder)\n* Python: [`pulumi_synced_folder`](https://pypi.org/project/pulumi-synced-folder/)\n* Go: [`github.com/pulumi/pulumi-synced-folder/sdk/go/synced-folder`](https://github.com/pulumi/pulumi-synced-folder/)\n* .NET: [`Pulumi.SyncedFolder`](https://www.nuget.org/packages/Pulumi.SyncedFolder)\n* YAML\n\n## Using the component\n\nGiven a cloud-storage bucket and the path to a local folder, the component synchronizes files from the folder to the bucket, deleting any files in the destination bucket that don't exist locally. It does this in one of two ways:\n\n* By managing each file as an individual Pulumi resource (`aws.s3.BucketObject`, `azure.storage.Blob`, or `gcp.storage.BucketObject`). This is the component's default behavior.\n\n* By delegating sync responsibility to a cloud provider CLI (e.g., [`aws`](https://aws.amazon.com/cli/), [`az`](https://docs.microsoft.com/en-us/cli/azure/), or [`gcloud`/`gsutil`](https://cloud.google.com/storage/docs/gsutil)). This behavior is enabled by setting the `managedObjects` input property to `false` and ensuring the relevant CLI tool is installed alongside `pulumi`.\n\nThe former approach — having Pulumi manage your resources for you — is generally preferable, but in some cases, for example a website consisting of thousands of files, it may not be the best fit. This component lets you choose the approach that works best for you, without having to brek out of your Pulumi program or workflow.\n\nBelow are a few examples in Pulumi YAML, each of which assumes the existence of a `site` folder containing one or more files to be uploaded. See the [examples](./examples) folder for additional languages and scenarios.\n\n### Sync to an S3 bucket\n\nHere, a local folder, `./site`, is pushed to Amazon S3, its contents managed as individual `s3.BucketObject`s:\n\n\n```yaml\nname: synced-folder-examples-aws-yaml\nruntime: yaml\ndescription: An example of using the synced-folder component.\n\nresources:\n\n s3-bucket:\n type: aws:s3:Bucket\n properties:\n acl: public-read\n website:\n indexDocument: index.html\n errorDocument: error.html\n\n # \ud83d\udc47\n synced-bucket-folder:\n type: synced-folder:index:S3BucketFolder\n properties:\n path: ./site\n bucketName: ${s3-bucket.bucket}\n acl: public-read\n\noutputs:\n url: http://${s3-bucket.websiteEndpoint}\n```\n\n### Sync to an Azure Blob Storage container\n\nHere, the folder's contents are synced to an Azure Blob Storage container, but instead of managing each file as an `azure.storage.Blob`, the component invokes the Azure CLI (specifically the `az storage blob sync` command) with [Pulumi Command](https://www.pulumi.com/registry/packages/command/). The optional `managedObjects` property lets you configure this behavior on a folder-by-folder basis.\n\n```yaml\nname: synced-folder-examples-azure-yaml\nruntime: yaml\ndescription: An example of using the synced-folder component in YAML.\n\nresources:\n\n resource-group:\n type: azure-native:resources:ResourceGroup\n\n storage:\n type: azure-native:storage:StorageAccount\n properties:\n resourceGroupName: ${resource-group.name}\n kind: StorageV2\n sku:\n name: Standard_LRS\n\n website:\n type: azure-native:storage:StorageAccountStaticWebsite\n properties:\n resourceGroupName: ${resource-group.name}\n accountName: ${storage.name}\n indexDocument: index.html\n error404Document: error.html\n\n # \ud83d\udc47\n synced-azure-blob-folder:\n type: synced-folder:index:AzureBlobFolder\n properties:\n path: ./site\n resourceGroupName: ${resource-group.name}\n storageAccountName: ${storage.name}\n containerName: ${website.containerName}\n managedObjects: false # \ud83d\udc48 Sync files with the Azure CLI.\n\noutputs:\n url: ${storage.primaryEndpoints.web}\n```\n\n### Sync to a Google Cloud Storage bucket\n\nHere, `./site` is synced to a Google Cloud Storage bucket.\n\n```yaml\nname: synced-folder-examples-google-cloud-yaml\nruntime: yaml\ndescription: An example of using the synced-folder component in YAML.\n\nresources:\n\n gcp-bucket:\n type: gcp:storage:Bucket\n properties:\n location: US\n website:\n mainPageSuffix: index.html\n notFoundPage: error.html\n\n gcp-bucket-iam-binding:\n type: gcp:storage:BucketIAMBinding\n properties:\n bucket: ${gcp-bucket.name}\n role: roles/storage.objectViewer\n members:\n - allUsers\n\n # \ud83d\udc47\n synced-google-cloud-folder:\n type: synced-folder:index:GoogleCloudFolder\n properties:\n path: ./site\n bucketName: ${gcp-bucket.name}\n\noutputs:\n url: https://storage.googleapis.com/${gcp-bucket.name}/index.html\n```\n\n## Configuration\n\n\nThe following input properties are common to all three resource types:\n\n| Property | Type | Description |\n| -------- | ---- | ----------- |\n| `path` | `string` | The path (relative or fully-qualified) to the folder containing the files to be synced. Required. |\n| `managedObjects` | `boolean` | Whether to have Pulumi manage files as individual cloud resources. Defaults to `true`. See below for details. |\n\nAdditional resource-specific properties are listed below.\n\n### `S3BucketFolder` properties\n\n| Property | Type | Description |\n| -------- | ---- | ----------- |\n| `bucketName` | `string` | The name of the S3 bucket to sync to (e.g., `my-bucket` in `s3://my-bucket`). Required. |\n| `acl` | `string` | The AWS [Canned ACL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl) to apply to each file (e.g., `public-read`). Required. |\n\n### `AzureBlobFolder` properties\n\n| Property | Type | Description |\n| -------- | ---- | ----------- |\n| `containerName` | `string` | The name of the Azure storage container to sync to. Required. |\n| `storageAccountName` | `string` | The name of the Azure storage account that the container belongs to. Required. |\n| `resourceGroupName` | `string` | The name of the Azure resource group that the storage account belongs to. Required. |\n\n### `GoogleCloudFolder` properties\n\n| Property | Type | Description |\n| -------- | ---- | ----------- |\n| `bucketName` | `string` | The name of the Google Cloud Storage bucket to sync to (e.g., `my-bucket` in `gs://my-bucket`). Required. |\n\n## Notes\n\n### Using the `managedObjects` property\n\nBy default, the component manages your files as individual Pulumi cloud resources, but you can opt out of this behavior by setting the component's `managedObjects` property to `false`. When you do this, the component assumes you've installed the appropriate CLI tool — [`aws`](https://aws.amazon.com/cli/), [`az`](https://docs.microsoft.com/en-us/cli/azure/), or [`gcloud`/`gsutil`](https://cloud.google.com/storage/docs/gsutil), depending on the cloud — and uses the [Command](https://www.pulumi.com/registry/packages/command/) provider to issue commands on that tool directly. Files are one-way synchronized only (local to remote), and files that exist remotely but not locally are deleted. All files are deleted from remote storage on `pulumi destroy`.\n\nThe component does not yet support switching seamlessly between `managedObjects: true` and `managedObjects: false`, however, so if you find after deploying a given folder with managed objects that you'd prefer to use unmanaged objects instead (or vice-versa), we recommend creating a second bucket/storage container and folder and removing the first. You can generally do this within the scope of a single program update. For example:\n\n```yaml\n# ...\n\nresources:\n\n # The original bucket and synced-folder resources, using managed file objects.\n #\n # my-first-bucket:\n # type: aws:s3:Bucket\n # properties:\n # acl: public-read\n # website:\n # indexDocument: index.html\n # errorDocument: error.html\n #\n # my-first-synced-folder:\n # type: synced-folder:index:S3BucketFolder\n # properties:\n # path: ./stuff\n # bucketName: ${my-first-bucket.bucket}\n # acl: public-read\n\n # A new bucket and synced-folder using unmanaged file objects.\n changed-my-mind-bucket:\n type: aws:s3:Bucket\n properties:\n acl: public-read\n website:\n indexDocument: index.html\n errorDocument: error.html\n\n changed-my-mind-synced-folder:\n type: synced-folder:index:S3BucketFolder\n properties:\n path: ./stuff\n bucketName: ${changed-my-mind-bucket.bucket}\n acl: public-read\n managedObjects: false\n\noutputs:\n\n # An updated program reference pointing to the new bucket.\n url: http://${changed-my-mind-bucket.websiteEndpoint}\n```\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "A Pulumi component that synchronizes a local folder to Amazon S3, Azure Blob Storage, or Google Cloud Storage.",
"version": "0.11.1",
"project_urls": {
"Homepage": "https://pulumi.com",
"Repository": "https://github.com/pulumi/pulumi-synced-folder"
},
"split_keywords": [
"pulumi",
"aws",
"azure",
"gcp",
"category/cloud",
"kind/component"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "72eb0c44399b45ef1ec3a2137ff02947248d4c2b6296b37be77165751956b0a2",
"md5": "9e944bd715e95c43bad86953b9ff7fff",
"sha256": "658864642f12ea313214bc041622513d50fc794051d673cc12836f83d9462813"
},
"downloads": -1,
"filename": "pulumi_synced_folder-0.11.1.tar.gz",
"has_sig": false,
"md5_digest": "9e944bd715e95c43bad86953b9ff7fff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 12554,
"upload_time": "2023-08-02T21:14:41",
"upload_time_iso_8601": "2023-08-02T21:14:41.392882Z",
"url": "https://files.pythonhosted.org/packages/72/eb/0c44399b45ef1ec3a2137ff02947248d4c2b6296b37be77165751956b0a2/pulumi_synced_folder-0.11.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-02 21:14:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pulumi",
"github_project": "pulumi-synced-folder",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pulumi-synced-folder"
}
JSON
