Merge pull request #5720 from streamnsight/update/oci-cherry-pick-for…

…-release-1.27

OCI provider - implement Workload Identity auth - cherry pick for release 1.27

cluster-autoscaler/cloudprovider/oci/README.md

@@ -49,6 +49,23 @@ Allow dynamic-group acme-oci-cluster-autoscaler-dyn-grp to use vnics in compartm
 Allow dynamic-group acme-oci-cluster-autoscaler-dyn-grp to inspect compartments in compartment <compartment-name>
 ```
 
+### If using Workload Identity
+
+Note: This is available to use with OKE Node Pools or OCI Managed Instance Pools with OKE Enhanced Clusters only. 
+
+See the [documentation](https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contenggrantingworkloadaccesstoresources.htm) for more details
+
+When using a mix of nodes, make sure to add proper lables and affinities on the cluster-autoscaler deployment to prevent it from being deployed on non-OCI managed nodes.
+
+```
+Allow any-user to manage cluster-node-pools in compartment <compartment name> where ALL {request.principal.type='workload', request.principal.namespace ='<namespace>', request.principal.service_account = 'cluster-autoscaler', request.principal.cluster_id = 'ocid1.cluster.oc1....'}
+Allow any-user to manage instance-family in compartment <compartment name> where ALL {request.principal.type='workload', request.principal.namespace ='<namespace>', request.principal.service_account = 'cluster-autoscaler', request.principal.cluster_id = 'ocid1.cluster.oc1....'}
+Allow any-user to use subnets in compartment <compartment name> where ALL {request.principal.type='workload', request.principal.namespace ='<namespace>', request.principal.service_account = 'cluster-autoscaler', request.principal.cluster_id = 'ocid1.cluster.oc1....'}
+Allow any-user to read virtual-network-family in compartment <compartment name> where ALL {request.principal.type='workload', request.principal.namespace ='<namespace>', request.principal.service_account = 'cluster-autoscaler', request.principal.cluster_id = 'ocid1.cluster.oc1....'}
+Allow any-user to use vnics in compartment <compartment name> where ALL {request.principal.type='workload', request.principal.namespace ='<namespace>', request.principal.service_account = 'cluster-autoscaler', request.principal.cluster_id = 'ocid1.cluster.oc1....'}
+Allow any-user to inspect compartments in compartment <compartment name> where ALL {request.principal.type='workload', request.principal.namespace ='<namespace>', request.principal.service_account = 'cluster-autoscaler', request.principal.cluster_id = 'ocid1.cluster.oc1....'}
+```
+
 ### Instance Pool and Instance Configurations
 
 Before you deploy the Cluster Autoscaler on OCI, your need to create one or more static Instance Pools and Instance
@@ -123,6 +140,7 @@ use-instance-principals = true
 ### Configuration via environment-variables:
 
 - `OCI_USE_INSTANCE_PRINCIPAL` - Whether to use Instance Principals for authentication rather than expecting an OCI config file to be mounted in the container. Defaults to false.
+- `OCI_USE_WORKLOAD_IDENTITY` - Whether to use Workload Identity for authentication (Available with node pools and OCI managed nodepools in OKE Enhanced Clusters only). Setting to `true` takes precedence over `OCI_USE_INSTANCE_PRINCIPAL`. When using this flag, the `OCI_RESOURCE_PRINCIPAL_VERSION` (1.1 or 2.2) and `OCI_RESOURCE_PRINCIPAL_REGION` also need to be set. See this [blog post](https://blogs.oracle.com/cloud-infrastructure/post/oke-workload-identity-greater-control-access#:~:text=The%20OKE%20Workload%20Identity%20feature,having%20to%20run%20fewer%20nodes.) for more details on setting the policies for this auth mode.
 - `OCI_REFRESH_INTERVAL` - Optional. Refresh interval to sync internal cache with OCI API. Defaults to `2m`.
 
 #### Instance Pool specific environment-variables

cluster-autoscaler/cloudprovider/oci/common/oci_cloud_config.go

@@ -12,7 +12,7 @@ import (
 	"gopkg.in/gcfg.v1"
 	ipconsts "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/instancepools/consts"
 	npconsts "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/nodepools/consts"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/common"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/common"
 	"k8s.io/klog/v2"
 )
 

cluster-autoscaler/cloudprovider/oci/common/oci_shape.go

@@ -7,13 +7,14 @@ package common
 import (
 	"context"
 	"fmt"
-	"github.com/pkg/errors"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/common"
-	oke "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/containerengine"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/core"
-	"k8s.io/klog/v2"
 	"sync"
 	"time"
+
+	"github.com/pkg/errors"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/common"
+	oke "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/containerengine"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/core"
+	"k8s.io/klog/v2"
 )
 
 // ShapeGetter returns the oci shape attributes for the pool.

cluster-autoscaler/cloudprovider/oci/common/oci_shape_test.go

@@ -6,13 +6,13 @@ package common
 
 import (
 	"context"
-	oke "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/containerengine"
+	oke "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/containerengine"
 	"reflect"
 	"strings"
 	"testing"
 
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/common"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/core"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/common"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/core"
 )
 
 type mockShapeClient struct {

cluster-autoscaler/cloudprovider/oci/common/oci_util.go

@@ -7,17 +7,18 @@ package common
 import (
 	"context"
 	"fmt"
-	"k8s.io/client-go/kubernetes"
-	"k8s.io/klog/v2"
 	"math"
 	"net"
 	"net/http"
 	"strings"
 	"time"
 
+	"k8s.io/client-go/kubernetes"
+	"k8s.io/klog/v2"
+
 	"github.com/pkg/errors"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/common"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/common"
 )
 
 // IsRetryable returns true if the given error is retryable.

cluster-autoscaler/cloudprovider/oci/instancepools/consts/annotations.go

@@ -10,6 +10,8 @@ import (
 )
 
 const (
+	// OciUseWorkloadIdentityEnvVar is an env var that indicates whether to use the workload identity provider
+	OciUseWorkloadIdentityEnvVar = "OCI_USE_WORKLOAD_IDENTITY"
 	// OciUseInstancePrincipalEnvVar is an env var that indicates whether to use an instance principal
 	OciUseInstancePrincipalEnvVar = "OCI_USE_INSTANCE_PRINCIPAL"
 	// OciUseNonPoolMemberAnnotationEnvVar is an env var indicating that non-members of instance pools will get a special annotation

cluster-autoscaler/cloudprovider/oci/instancepools/oci_instance_pool_cache.go

@@ -7,18 +7,19 @@ package instancepools
 import (
 	"context"
 	"fmt"
+	"math"
+	"strings"
+	"sync"
+	"time"
+
 	"github.com/pkg/errors"
 	"k8s.io/apimachinery/pkg/util/wait"
 	ocicommon "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/common"
 	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/instancepools/consts"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/common"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/core"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/workrequests"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/common"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/core"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/workrequests"
 	"k8s.io/klog/v2"
-	"math"
-	"strings"
-	"sync"
-	"time"
 )
 
 // ComputeMgmtClient wraps core.ComputeManagementClient exposing the functions we actually require.

cluster-autoscaler/cloudprovider/oci/instancepools/oci_instance_pool_manager.go

@@ -6,13 +6,14 @@ package instancepools
 
 import (
 	"fmt"
-	ocicommon "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/common"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/instancepools/consts"
 	"os"
 	"strconv"
 	"strings"
 	"time"
 
+	ocicommon "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/common"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/instancepools/consts"
+
 	apiv1 "k8s.io/api/core/v1"
 	"k8s.io/apimachinery/pkg/api/resource"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
@@ -23,10 +24,10 @@ import (
 	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider"
 
 	"github.com/pkg/errors"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/common"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/common/auth"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/core"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/workrequests"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/common"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/common/auth"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/core"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/workrequests"
 )
 
 var (
@@ -79,12 +80,21 @@ func CreateInstancePoolManager(cloudConfigPath string, discoveryOpts cloudprovid
 		RetryPolicy: ocicommon.NewRetryPolicy(),
 	}
 
-	if os.Getenv(consts.OciUseInstancePrincipalEnvVar) == "true" {
+	// Preference to Workload Identity if set to true
+	if os.Getenv(consts.OciUseWorkloadIdentityEnvVar) == "true" {
+		klog.V(4).Info("using workload identity...")
+		configProvider, err = auth.OkeWorkloadIdentityConfigurationProvider()
+		if err != nil {
+			return nil, err
+		}
+		// try instance principal is set to true
+	} else if os.Getenv(consts.OciUseInstancePrincipalEnvVar) == "true" {
 		klog.V(4).Info("using instance principals...")
 		configProvider, err = auth.InstancePrincipalConfigurationProvider()
 		if err != nil {
 			return nil, err
 		}
+		// default to default provider
 	} else {
 		klog.Info("using default configuration provider")
 		configProvider = common.DefaultConfigProvider()

cluster-autoscaler/cloudprovider/oci/instancepools/oci_instance_pool_manager_test.go

@@ -8,14 +8,14 @@ import (
 	"context"
 	apiv1 "k8s.io/api/core/v1"
 	ocicommon "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/common"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/core"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/workrequests"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/core"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/workrequests"
 	kubeletapis "k8s.io/kubelet/pkg/apis"
 	"reflect"
 	"testing"
 
 	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/common"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/common"
 )
 
 // this is a copy of the mockShapeClient code in common/oci_shape_test.go

cluster-autoscaler/cloudprovider/oci/nodepools/cache.go

@@ -12,8 +12,8 @@ import (
 	"k8s.io/klog/v2"
 
 	"github.com/pkg/errors"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/common"
-	oke "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/containerengine"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/common"
+	oke "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/containerengine"
 )
 
 func newNodePoolCache(okeClient *oke.ContainerEngineClient) *nodePoolCache {

cluster-autoscaler/cloudprovider/oci/nodepools/oci_manager.go

@@ -25,10 +25,10 @@ import (
 	ocicommon "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/common"
 	ipconsts "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/instancepools/consts"
 	npconsts "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/nodepools/consts"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/common"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/common/auth"
-	oke "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/containerengine"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/core"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/common"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/common/auth"
+	oke "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/containerengine"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/core"
 )
 
 const (
@@ -82,7 +82,13 @@ func CreateNodePoolManager(cloudConfigPath string, discoveryOpts cloudprovider.N
 	var err error
 	var configProvider common.ConfigurationProvider
 
-	if os.Getenv(ipconsts.OciUseInstancePrincipalEnvVar) == "true" || os.Getenv(npconsts.OkeUseInstancePrincipalEnvVar) == "true" {
+	if os.Getenv(ipconsts.OciUseWorkloadIdentityEnvVar) == "true" {
+		klog.Info("using workload identity provider")
+		configProvider, err = auth.OkeWorkloadIdentityConfigurationProvider()
+		if err != nil {
+			return nil, err
+		}
+	} else if os.Getenv(ipconsts.OciUseInstancePrincipalEnvVar) == "true" || os.Getenv(npconsts.OkeUseInstancePrincipalEnvVar) == "true" {
 		klog.Info("using instance principal provider")
 		configProvider, err = auth.InstancePrincipalConfigurationProvider()
 		if err != nil {

cluster-autoscaler/cloudprovider/oci/nodepools/oci_manager_test.go

@@ -13,11 +13,11 @@ import (
 
 	apiv1 "k8s.io/api/core/v1"
 	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider"
-	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/common"
+	"k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/common"
 	kubeletapis "k8s.io/kubelet/pkg/apis"
 
 	ocicommon "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/common"
-	oke "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/containerengine"
+	oke "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/containerengine"
 )
 
 func TestNodePoolFromArgs(t *testing.T) {

cluster-autoscaler/cloudprovider/oci/nodepools/registered_taints.go

@@ -11,7 +11,7 @@ import (
 	apiv1 "k8s.io/api/core/v1"
 	taintutil "k8s.io/kubernetes/pkg/util/taints"
 
-	oke "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/containerengine"
+	oke "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/containerengine"
 )
 
 // RegisteredTaintsGetter returns the initial registered taints for the node pool.

cluster-autoscaler/cloudprovider/oci/nodepools/registered_taints_test.go

@@ -9,7 +9,7 @@ import (
 	"testing"
 
 	apiv1 "k8s.io/api/core/v1"
-	oke "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v55/containerengine"
+	oke "k8s.io/autoscaler/cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/oracle/oci-go-sdk/v65/containerengine"
 )
 
 func Test_ociInitialTaintsGetterImpl_Get(t *testing.T) {

cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/gofrs/flock/.gitignore

@@ -0,0 +1,24 @@
+# Compiled Object files, Static and Dynamic libs (Shared Objects)
+*.o
+*.a
+*.so
+
+# Folders
+_obj
+_test
+
+# Architecture specific extensions/prefixes
+*.[568vq]
+[568vq].out
+
+*.cgo1.go
+*.cgo2.c
+_cgo_defun.c
+_cgo_gotypes.go
+_cgo_export.*
+
+_testmain.go
+
+*.exe
+*.test
+*.prof

cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/gofrs/flock/.travis.yml

@@ -0,0 +1,10 @@
+language: go
+go:
+  - 1.14.x
+  - 1.15.x
+script: go test -v -check.vv -race ./...
+sudo: false
+notifications:
+  email:
+    on_success: never
+    on_failure: always

cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/gofrs/flock/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2015-2020, Tim Heckman
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of gofrs nor the names of its contributors may be used
+  to endorse or promote products derived from this software without
+  specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

cluster-autoscaler/cloudprovider/oci/vendor-internal/github.com/gofrs/flock/README.md

@@ -0,0 +1,41 @@
+# flock
+[![TravisCI Build Status](https://img.shields.io/travis/gofrs/flock/master.svg?style=flat)](https://travis-ci.org/gofrs/flock)
+[![GoDoc](https://img.shields.io/badge/godoc-flock-blue.svg?style=flat)](https://godoc.org/github.com/gofrs/flock)
+[![License](https://img.shields.io/badge/license-BSD_3--Clause-brightgreen.svg?style=flat)](https://github.com/gofrs/flock/blob/master/LICENSE)
+[![Go Report Card](https://goreportcard.com/badge/github.com/gofrs/flock)](https://goreportcard.com/report/github.com/gofrs/flock)
+
+`flock` implements a thread-safe sync.Locker interface for file locking. It also
+includes a non-blocking TryLock() function to allow locking without blocking execution.
+
+## License
+`flock` is released under the BSD 3-Clause License. See the `LICENSE` file for more details.
+
+## Go Compatibility
+This package makes use of the `context` package that was introduced in Go 1.7. As such, this
+package has an implicit dependency on Go 1.7+.
+
+## Installation
+```
+go get -u github.com/gofrs/flock
+```
+
+## Usage
+```Go
+import "github.com/gofrs/flock"
+
+fileLock := flock.New("/var/lock/go-lock.lock")
+
+locked, err := fileLock.TryLock()
+
+if err != nil {
+	// handle locking error
+}
+
+if locked {
+	// do work
+	fileLock.Unlock()
+}
+```
+
+For more detailed usage information take a look at the package API docs on
+[GoDoc](https://godoc.org/github.com/gofrs/flock).