Skip to content

Commit bd9ffc8

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #7 from PatrickGhadban/main
Update README instructions
2 parents e20ceda + 30d9c8e commit bd9ffc8

File tree

6 files changed

+150
-50
lines changed

6 files changed

+150
-50
lines changed

‎CHANGELOG-0.x.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
11
# v0.1.0
22

3+
[//]: # (TODO: Create v0.1.0 branch)
4+
[Documentation](https://github.com/kubernetes-sigs/aws-file-cache-csi-driver/blob/v0.1.0/docs/README.md)
35

6+
### Notable changes
7+
* Add suppport for Static Provisioning ([#2](https://github.com/kubernetes-sigs/aws-file-cache-csi-driver/pull/2), [@PatrickGhadban](https://github.com/PatrickGhadban/))
8+
* Add suppport for Dynamic Provisioning ([#5](https://github.com/kubernetes-sigs/aws-file-cache-csi-driver/pull/5), [@jacobwolfaws](https://github.com/jacobwolfaws/))
9+
* Add helm install ([#6](https://github.com/kubernetes-sigs/aws-file-cache-csi-driver/pull/6), [@jacobwolfaws](https://github.com/jacobwolfaws/))

‎Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ GOPATH=$(shell go env GOPATH)
2626
GOOS=$(shell go env GOOS)
2727
GOBIN=$(shell pwd)/bin
2828

29-
IMAGE?=651262257939.dkr.ecr.us-east-1.amazonaws.com/file-cache-dynamic-provisioning
29+
IMAGE?=648284600874.dkr.ecr.us-east-1.amazonaws.com/file-cache-dynamic-provisioning
3030
TAG?=$(GIT_COMMIT)
3131

3232
OUTPUT_TYPE?=docker

‎README.md‎

Lines changed: 143 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
[![Build Status](https://travis-ci.org/kubernetes-sigs/aws-file-cache-csi-driver.svg?branch=master)](https://travis-ci.org/kubernetes-sigs/aws-fsx-csi-driver)
2-
[![Coverage Status](https://coveralls.io/repos/github/kubernetes-sigs/aws-file-cache-csi-driver/badge.svg?branch=master)](https://coveralls.io/github/kubernetes-sigs/aws-file-cache-csi-driver?branch=master)
31
[![Go Report Card](https://goreportcard.com/badge/github.com/kubernetes-sigs/aws-file-cache-csi-driver)](https://goreportcard.com/report/github.com/kubernetes-sigs/aws-file-cache-csi-driver)
42

53
**WARNING**: This driver is in pre ALPHA currently. This means that there may potentially be backwards compatible breaking changes moving forward. Do NOT use this driver in a production environment in its current state.
@@ -9,97 +7,200 @@
97
## Amazon File Cache CSI Driver
108
### Overview
119

12-
The [Amazon File Cache]() Container Storage Interface (CSI) Driver provides a [CSI]() interface used by container orchestrators to manage the lifecycle of Amazon file cache volumes.
13-
14-
This driver is in alpha stage. Basic volume operations that are functional include NodePublishVolume/NodeUnpublishVolume.
10+
The [Amazon File Cache](https://docs.aws.amazon.com/fsx/latest/FileCacheGuide/) Container Storage Interface (CSI) Driver provides a [CSI](https://github.com/container-storage-interface/spec/blob/master/spec.md) interface used by container orchestrators to manage the lifecycle of Amazon file cache volumes.
1511

1612
### CSI Specification Compability Matrix
17-
| AWS File Cache CSI Driver \ CSI Version | v1.0.0|
18-
|---------------------------------------------------|-------|
19-
| master branch | yes |
13+
| AWS File Cache CSI Driver \ CSI Version | v1.x.x |
14+
|-----------------------------------------|--------|
15+
| v0.1.0 | yes |
2016

2117
### Features
22-
Currently only static provisioning is supported. With static provisioning, a file cache should be created manually, then it could be mounted inside container as a persistence volume (PV) using File Cache CSI Driver.
2318

2419
The following CSI interfaces are implemented:
25-
* Controller Service:
20+
* Controller Service: CreateVolume, DeleteVolume, ControllerGetCapabilities, ValidateVolumeCapabilities
2621
* Node Service: NodePublishVolume, NodeUnpublishVolume, NodeGetCapabilities, NodeGetInfo, NodeGetId
2722
* Identity Service: GetPluginInfo, GetPluginCapabilities, Probe
2823

2924
## Amazon File Cache CSI Driver on Kubernetes
3025

31-
---------
3226
The following sections are Kubernetes-specific. If you are a Kubernetes user, use the following for driver features, installation steps and examples.
3327

3428
### Kubernetes Version Compability Matrix
35-
| AWS File Cache CSI Driver \ Kubernetes Version | v1.24+ |
36-
|---------------------------------------------------|--------|
37-
| master branch | yes |
29+
| AWS File Cache CSI Driver \ Kubernetes Version | v1.22+ |
30+
|------------------------------------------------|--------|
31+
| v0.1.0 | yes |
3832

3933
### Container Images
40-
| File Cache CSI Driver Version | Image |
41-
|-------------------------------|---------------------------------------------------------------|
42-
| master branch | public.ecr.aws/fsx-csi-driver/aws-filecache-csi-driver:latest |
34+
| File Cache CSI Driver Version | Image |
35+
|-------------------------------|---------------------------------------------------------------------|
36+
| v0.1.0 | public.ecr.aws/file-cache-csi-driver/aws-file-cache-csi-driver:v0.1.0 |
4337

4438
### Features
4539
* Static provisioning - Amazon File Cache needs to be created manually first, then it could be mounted inside container as a volume using the Driver.
46-
* Dynamic provisioning (currently not supported) - uses persistent volume claim (PVC) to let Kubernetes create the Amazon File Cache for you and consumes the volume from inside container.
40+
* Dynamic provisioning - uses persistent volume claim (PVC) to let Kubernetes create the Amazon File Cache for you and consumes the volume from inside container.
4741
* Mount options - mount options can be specified in storageclass to define how the volume should be mounted.
4842

4943
**Notes**:
5044
* For dynamically provisioned volumes, only one subnet is allowed inside a storageclass's `parameters.subnetId`. This is a [limitation](https://docs.aws.amazon.com/fsx/latest/APIReference/API_FileCacheCreating.html#FSx-Type-FileCacheCreating-SubnetIds) that is enforced by Amazon File Cache.
5145

5246
### Installation
53-
#### Set up driver permission
54-
The driver requires IAM permission to talk to Amazon File Cache service to create/delete the filecache on user's behalf. There are several methods to grant driver IAM permission:
55-
* Using secret object - create an IAM user with proper permission, put that user's credentials in [secret manifest](../deploy/kubernetes/secret.yaml) then deploy the secret.
56-
57-
```sh
58-
curl https://raw.githubusercontent.com/kubernetes-sigs/aws-file-cache-csi-driver/master/deploy/kubernetes/secret.yaml > secret.yaml
59-
# Edit the secret with user credentials
60-
kubectl apply -f secret.yaml
47+
#### 1. Set a few variables to use in the remaining steps. Replace `my-csi-filecache` with the name of the test cluster you want to create and `region-code` with the AWS Region that you want to create your test cluster in.
48+
```shell
49+
export cluster_name=my-csi-filecache
50+
export region_code=region-code
6151
```
6252

63-
* Using worker node instance profile - grant all the worker nodes with proper permission by attach policy to the instance profile of the worker.
64-
```sh
65-
`kubectl annotate serviceaccount -n kube-system file-cache-csi-controller-sa \
66-
eks.amazonaws.com/role-arn=arn:aws:iam::111111111111:role/AmazonEKSFileCacheCSIDriverFullAccess --overwrite=true
53+
#### 2. Create a test cluster.
54+
```shell
55+
eksctl create cluster \
56+
--name $cluster_name \
57+
--region $region_code \
58+
--with-oidc \
59+
--ssh-access \
60+
--ssh-public-key my-key
6761
```
6862

63+
#### 3. Set up driver permission
64+
The driver requires IAM permission to talk to Amazon File Cache service to create/delete the filecache on user's behalf. There are several methods to grant driver IAM permission:
6965

70-
#### Deploy driver
71-
```sh
72-
kubectl apply -k deploy/kubernetes/base/
66+
* Create a Kubernetes service account for the driver and attach the `AmazonFSxFullAccess` AWS-managed policy to the service account with the following command. If your cluster is in the AWS GovCloud (US-East) or AWS GovCloud (US-West) AWS Regions, then replace `arn:aws:` with `arn:aws-us-gov:`.
67+
68+
```shell
69+
eksctl create iamserviceaccount \
70+
--name filecache-csi-controller-sa \
71+
--namespace kube-system \
72+
--cluster $cluster_name \
73+
--attach-policy-arn arn:aws:iam::aws:policy/AmazonFSxFullAccess \
74+
--approve \
75+
--role-name AmazonEKSFileCacheCSIDriverFullAccess \
76+
--region $region_code
7377
```
7478

75-
TODO: Add helm installation option
76-
```sh
7779

80+
* Using worker node instance profile - grant all the worker nodes with proper permission by attach policy to the instance profile of the worker.
81+
```shell
82+
{
83+
"Version": "2012-10-17",
84+
"Statement": [
85+
{
86+
"Effect": "Allow",
87+
"Action": [
88+
"ds:DescribeDirectories",
89+
"fsx:*"
90+
],
91+
"Resource": "*"
92+
},
93+
{
94+
"Effect": "Allow",
95+
"Action": "iam:CreateServiceLinkedRole",
96+
"Resource": "*",
97+
"Condition": {
98+
"StringEquals": {
99+
"iam:AWSServiceName": [
100+
"fsx.amazonaws.com"
101+
]
102+
}
103+
}
104+
},
105+
{
106+
"Effect": "Allow",
107+
"Action": "iam:CreateServiceLinkedRole",
108+
"Resource": "*",
109+
"Condition": {
110+
"StringEquals": {
111+
"iam:AWSServiceName": [
112+
"s3.data-source.lustre.fsx.amazonaws.com"
113+
]
114+
}
115+
}
116+
},
117+
{
118+
"Effect": "Allow",
119+
"Action": [
120+
"logs:CreateLogGroup",
121+
"logs:CreateLogStream",
122+
"logs:PutLogEvents"
123+
],
124+
"Resource": [
125+
"arn:aws:logs:*:*:log-group:/aws/fsx/*"
126+
]
127+
},
128+
{
129+
"Effect": "Allow",
130+
"Action": [
131+
"firehose:PutRecord"
132+
],
133+
"Resource": [
134+
"arn:aws:firehose:*:*:deliverystream/aws-fsx-*"
135+
]
136+
},
137+
{
138+
"Effect": "Allow",
139+
"Action": [
140+
"ec2:CreateTags"
141+
],
142+
"Resource": [
143+
"arn:aws:ec2:*:*:route-table/*"
144+
],
145+
"Condition": {
146+
"StringEquals": {
147+
"aws:RequestTag/AmazonFSx": "ManagedByAmazonFSx"
148+
},
149+
"ForAnyValue:StringEquals": {
150+
"aws:CalledVia": [
151+
"fsx.amazonaws.com"
152+
]
153+
}
154+
}
155+
},
156+
{
157+
"Effect": "Allow",
158+
"Action": [
159+
"ec2:DescribeSecurityGroups",
160+
"ec2:DescribeSubnets",
161+
"ec2:DescribeVpcs"
162+
],
163+
"Resource": "*",
164+
"Condition": {
165+
"ForAnyValue:StringEquals": {
166+
"aws:CalledVia": [
167+
"fsx.amazonaws.com"
168+
]
169+
}
170+
}
171+
}
172+
]
173+
}
78174
```
79175

176+
#### 4. Deploy driver
177+
```sh
178+
kubectl apply -k "github.com/kubernetes-sigs/aws-file-cache-csi-driver/deploy/kubernetes/base/?ref=HEAD"
179+
```
80180

181+
Alternatively, you could also install the driver using helm:
81182

82183

184+
TODO: Add helm installation option
185+
```sh
83186

84-
------------------
85-
187+
```
86188

87189
### Examples
88190
Before the example, you need to:
89191
* Get yourself familiar with how to setup Kubernetes on AWS and [create Anmazon File Cache](https://docs.aws.amazon.com/fsx/latest/FileCacheGuide/getting-started.html) if you are using static provisioning.
90192
* When creating Amazon File Cache, make sure its VPC is accessible from Kuberenetes cluster's VPC and network traffic is allowed by security group.
91-
* For FSx for Lustre VPC, you can either create an Amazon File Cache inside the same VPC as Kubernetes cluster or using VPC peering.
92-
* For security group, make sure port 988 is allowed for the security groups that are attached the lustre filesystem ENI.
193+
* For Amazon File Cache VPC, you can either create an Amazon File Cache inside the same VPC as Kubernetes cluster or using VPC peering.
194+
* For security group, make sure port 988 is allowed for the security groups that are attached the file cache ENI.
93195
* Install Amazon File Cache CSI driver following the [Installation](README.md#Installation) steps.
94196

95197
#### Example Links
96198
* [Static provisioning](examples/kubernetes/static_provisioning/README.md)
97199
* [Dynamic provisioning](examples/kubernetes/dynamic_provisioning/README.md)
98-
* [Accessing the filesystem from multiple pods](examples/kubernetes/multiple_pods/README.md)
200+
* [Accessing the file cache from multiple pods](examples/kubernetes/multiple_pods/README.md)
99201

100202
## Development
101203

102-
----
103204
Please go through [CSI Spec](https://github.com/container-storage-interface/spec/blob/master/spec.md) and [General CSI driver development guideline](https://kubernetes-csi.github.io/docs/Development.html) to get some basic understanding of CSI driver before you start.
104205

105206
### Requirements
@@ -113,6 +214,6 @@ To execute all unit tests, run: `make test`
113214

114215
## License
115216

116-
----
217+
117218
This library is licensed under the Apache 2.0 License.
118219

‎examples/kubernetes/dynamic_provisioning/README.md‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,5 @@
11
## Dynamic Provisioning Example
22

3-
---
4-
5-
*~Not yet supported~*
63

74
This example shows how to create an Amazon File Cache using persistence volume claim (PVC) and consumes it from a pod. Please see the [CreateFileCache API Reference](https://docs.aws.amazon.com/fsx/latest/APIReference/API_CreateFileCache.html#FSx-CreateFileCache-request-DataRepositoryAssociations) for more information.
85

‎examples/kubernetes/multiple_pods/README.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
## Multiple Pods Read Write Many
22

3-
---
4-
53
This example shows how to create a dynamically provisioned Amazon File Cache PV and access it from multiple pods with ReadWriteMany access mode. If you are using static provisioning, following steps to setup static provisioned PV with access mode set to ReadWriteMany and the rest of steps of consuming the volume from pods are similar.
64

75
### Edit [StorageClass](specs/storageclass.yaml)

‎examples/kubernetes/static_provisioning/README.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
## Static Provisioning Example
22

3-
---
4-
53
This example shows how to make a pre-created Amazon File Cache mounted inside container.
64

75
### Edit [Persistent Volume Spec](specs/pv.yaml)

0 commit comments

Comments
 (0)