Skip to content

Commit

Permalink
Initial commit
Browse files Browse the repository at this point in the history
This is the initial proposal for the csi-lib-iscsi package (formerly a
part of github.com/j-griffith/csi-connectors).

There's likely to be some things to discuss and change, but this is the
first attempt.
  • Loading branch information
j-griffith committed Oct 25, 2018
1 parent 64d37cf commit d9b1722
Show file tree
Hide file tree
Showing 7 changed files with 891 additions and 11 deletions.
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
*.out
_output
example/example
15 changes: 15 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
.PHONY: all build clean install

all: clean build install

clean:
go clean -r -x
-rm -rf _output

build:
go build ./iscsi/
go build -o _output/example ./example/main.go

install:
go install ./iscsi/

46 changes: 35 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,39 @@
# Kubernetes Template Project
# csi lib-iscsi

The Kubernetes Template Project is a template for starting new projects in the GitHub organizations owned by Kubernetes. All Kubernetes projects, at minimum, must have the following files:
A simple go package intended to assist CSI plugin authors by providing a tool set to manage iscsi connections.

- a `README.md` outlining the project goals, sponsoring sig, and community contact information
- an `OWNERS` with the project leads listed as approvers ([docs on `OWNERS` files][owners])
- a `CONTRIBUTING.md` outlining how to contribute to the project
- an unmodified copy of `code-of-conduct.md` from this repo, which outlines community behavior and the consequences of breaking the code
- a `LICENSE` which must be Apache 2.0 for code projects, or [Creative Commons 4.0] for documentation repositories, without any custom content
- a `SECURITY_CONTACTS` with the contact points for the Product Security Team
to reach out to for triaging and handling of incoming issues. They must agree to abide by the
[Embargo Policy](https://github.com/kubernetes/sig-release/blob/master/security-release-process-documentation/security-release-process.md#embargo-policy)
and will be removed and replaced if they violate that agreement.
## Goals

Provide a basic, lightweight library for CSI Plugin Authors to leverage some of the common tasks like connecting
and disconnecting iscsi devices to a node. This library includes a high level abstraction for iscsi that exposes
simple Connect and Disconnect functions. These are built on top of exported iscsiadm calls, so if you need more
control you can access the iscsiadm calls directly.

## Design Philosophy

The idea is to keep this as lightweight and generic as possible. We intentionally avoid the use of any third party
libraries or packages in this project. We don't have a vendor directory, because we attempt to rely only on the std
golang libs. This may prove to not be ideal, and may be changed over time, but initially it's a worthwhile goal.

## Logging and Debug

By default the library does not provide any logging, but provides an error message that includes any messages from
iscsiadm as well as exit-codes. In the even that you need to debug the library, we provide a function:

```
func EnableDebugLogging(writer io.Writer)
```

This will turn on verbose logging directed to the provided io.Writer and include the response of every iscsiadm command
issued.

## Intended Usage

Curently the intended usage of this library is simply to provide a golang package to standardize how plugins are implementing
iscsi connect and disconnect. It's not intended to be a "service", although that's a possible next step. It's currenty been
used for plugins where iscsid is installed in containers only, as well as designs where it uses the nodes iscsid. Each of these
approaches has their own pros and cons. Currently, it's up to the plugin author to determine which model suits them best
and to deploy their node plugin appropriately.

## Community, discussion, contribution, and support

Expand All @@ -19,6 +42,7 @@ Learn how to engage with the Kubernetes community on the [community page](http:/
You can reach the maintainers of this project at:

- [Slack](http://slack.k8s.io/)
* sig-storage
- [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-dev)

### Code of conduct
Expand Down
75 changes: 75 additions & 0 deletions example/main.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
package main

import (
"flag"
"log"
"os"
"strings"
"time"

"github.com/kubernetes-csi/csi-lib-iscsi/iscsi"
)

var (
portals = flag.String("portals", "192.168.1.112:3260", "Comma delimited. Eg: 1.1.1.1,2.2.2.2")
iqn = flag.String("iqn", "iqn.2010-10.org.openstack:volume-95739000-1557-44f8-9f40-e9d29fe6ec47", "")
multipath = flag.Bool("multipath", false, "")
username = flag.String("username", "3aX7EEf3CEgvESQG75qh", "")
password = flag.String("password", "eJBDC7Bt7WE3XFDq", "")
lun = flag.Int("lun", 1, "")
debug = flag.Bool("debug", false, "enable logging")
)

func main() {
flag.Parse()
tgtp := strings.Split(*portals, ",")
if *debug {
iscsi.EnableDebugLogging(os.Stdout)
}

// You can utilize the iscsiadm calls directly if you wish, but by creating a Connector
// you can simplify interactions to simple calls like "Connect" and "Disconnect"
c := iscsi.Connector{
// Our example uses chap
AuthType: "chap",
// Specify the target iqn we're dealing with
TargetIqn: *iqn,
// List of portals must be >= 1 (>1 signals multipath/mpio)
TargetPortals: tgtp,
// CHAP can be setup up for discovery as well as sessions, our example
// device only uses CHAP security for sessions, for those that use Discovery
// as well, we'd add a DiscoverySecrets entry the same way
SessionSecrets: iscsi.Secrets{
UserName: *username,
Password: *password,
SecretsType: "chap"},
// Lun is the lun number the devices uses for exports
Lun: int32(*lun),
// Multipath indicates that we want to configure this connection as a multipath device
Multipath: *multipath,
// Number of times we check for device path, waiting for CheckInterval seconds inbetween each check (defaults to 10 if omitted)
RetryCount: 11,
// CheckInterval is the time in seconds to wait inbetween device path checks when logging in to a target
CheckInterval: 1,
}

// Now we can just issue a connection request using our Connector
// A succesful connection will include the device path to access our iscsi volume
path, err := iscsi.Connect(c)
if err != nil {
log.Printf("Error returned from iscsi.Connect: %s", err.Error())
os.Exit(1)
}

if path == "" {
log.Printf("Failed to connect, didn't receive a path, but also no error!")
os.Exit(1)
}

log.Printf("Connected device at path: %s\n", path)
time.Sleep(3 * time.Second)

// Disconnect is easy as well, we don't need the full Connector any more, just the Target IQN and the Portals
/// this should disconnect the volume as well as clear out the iscsi DB entries associated with it
iscsi.Disconnect(c.TargetIqn, c.TargetPortals)
}
Loading

0 comments on commit d9b1722

Please sign in to comment.